Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
20.5 KB
Raw Blame
import type { BrainEngine, NewFact } from '../engine.ts';
import type { GBrainConfig } from '../config.ts';
import { opError } from '../ops/contract.ts';
import { pageIdentityError, rememberAcceptsPageCreatedSince } from './page-identity.ts';
import { assertPageRevision } from '../page-state/types.ts';
import { assertFactNotWithdrawn, decideReplacement, decideSingleFact, prepareFactEmbedding, type SingleFactIntent } from '../facts/single-prepare.ts';
import { supersededValidUntil } from '../facts/supersede-interval.ts';
import { factEmbeddingDisabled } from '../embedding-disabled.ts';
import { engineMutationPrecondition, parseMutationPrecondition } from './preconditions.ts';
import type { PreparedMutation } from './coordinator.ts';
import type { WriteRequest } from './model.ts';
import type { ClaimPhaseClock } from './claim-phase.ts';
import { appendContextNote, type InferredVia } from '../facts/subject-infer.ts';
import { inferenceNote } from '../facts/subject-infer-write.ts';
import { requestChannelTrust } from '../trust/channel.ts';
import { gateField, gateInput, heldOutcome, loadWriteGateConfig } from '../trust/gate-outcomes.ts';
import { decideFactWrite, recordFlaggedRow, recordWriteGateHold } from '../write-gate-store.ts';
import { writeGateRejectedError } from '../write-gate.ts';
import { lexicalContestCandidate, recordContestedFact, recordHeldShare, restatedPrivateCopy, supersessionGuarded } from '../trust/supersede-handlers.ts';
import { storedTrustTier } from '../trust/tier.ts';
import { fenceAppendPendingTier } from '../eligibility/fence-overlay.ts';
import { prepareFenceFactAppend, prepareFenceFactCreate, prepareFenceRowRetirement, requestReceiptFix, type FenceFactAppend } from '../facts/fence-fact-append.ts';
import { remoteProvenanceFloorSql, resolveExcludePrivatePages, withFolderRestricted } from '../search/private-visibility.ts';
import { tightenToPage } from '../facts/visibility.ts';
import { isHoldingSlug } from '../facts-fence.ts';
import { noteBelief } from '../belief/ledger.ts';
import { attestedShareRefused, MEMBER_PAGE_PREFIX, memberPageFrontmatter, memberPageIsOwn, memberPageNotOwned, onOwnedMemoryPageSql, scopePageFrontmatter, scopePageIsShared, scopePageNotShared } from '../access/member-facts.ts';
import { claimColumns, storedClaim } from '../facts/typed-claim.ts';
import { parseStoredActor } from '../access/actor-model.ts';
import { withoutBody } from '../page-body/page-shape.ts';

function conflict(row: WriteRequest): never {
  throw opError('revision_conflict', 'The memory changed during semantic preparation.',
    `Another write changed the facts or entity page in source ${row.source_id} while remember request ${row.request_id} was prepared, so it did not save. Check that request's receipt; once it shows conflict, nothing was saved and remembering the fact again is safe.`,
    { fix: requestReceiptFix(row) });
}
function candidateState(value: Awaited<ReturnType<typeof decideSingleFact>>): string {
  const c = value.candidate;
  return JSON.stringify([value.status, c?.id, c?.fact, c?.kind, c?.visibility,
    c?.valid_until ? new Date(c.valid_until).toISOString() : null, c?.source_markdown_slug, c?.row_num, c?.trust_tier ?? null]);
}
export const NO_ENTITY_HINT = 'Saved without an entity, so entity-scoped recall will not find it. To link it, remember the same claim again with `entity` (the person, company or project it is about): that replaces this copy, so there is nothing to forget. Do not forget it: a claim forgotten without an entity is withdrawn for every entity and cannot be saved again.';
function outcome(id: number, status: 'inserted' | 'duplicate' | 'superseded', entitySlug: string | null, validUntil: Date | string | null, degraded: boolean, p: Record<string, unknown>, supersededId?: number, linkedCopy = false) {
  const statusText = status === 'inserted' ? `remembered as fact #${id}` : status === 'duplicate'
    ? `already knew this — kept fact #${id}` : linkedCopy
      ? `linked — fact #${id} replaces #${supersededId}, the same claim saved without an entity; nothing to forget`
      : `updated — fact #${id} supersedes the previous version`;
  return { id: String(id), status, status_text: statusText, entity_slug: entitySlug,
    ...(status === 'superseded' && supersededId !== undefined ? { superseded_fact_id: String(supersededId) } : {}),
    ...(status === 'superseded' && p.replaces !== undefined && p.replaces !== null ? { replaced_by_caller: true } : {}),
    valid_until: validUntil ? new Date(validUntil).toISOString() : null,
    ...(degraded ? { degraded_dedup: true } : {}),
    ...(entitySlug !== null && p.entity_inferred ? { entity_inferred: p.entity_inferred as InferredVia } : {}),
    ...(entitySlug === null ? { warnings: [p.entity_warning === 'ENTITY_LINK_FAILED' ? 'ENTITY_LINK_FAILED' : 'NO_ENTITY'], hint: NO_ENTITY_HINT } : {}),
    protocol_version: 1 };
}

/** The newest active fact in this source and visibility that states the same normalized claim without an entity. */
async function activeUnlinkedCopy(engine: BrainEngine, sourceId: string, input: SingleFactIntent, excludePrivate: boolean): Promise<number | null> {
  // GST-359 C2: a member's fact links only its own page's unlinked copy; no other write links one on a member page.
  const [row] = await engine.executeRaw<{ id: number }>(`SELECT id FROM facts
    WHERE source_id=$1 AND visibility=$2 AND entity_slug IS NULL AND expired_at IS NULL
      AND (valid_until IS NULL OR valid_until > now()) AND gbrain_fact_fingerprint(fact)=gbrain_fact_fingerprint($3)${excludePrivate && !input.page_slug ? ` AND ${remoteProvenanceFloorSql('facts')}` : ''}
      AND ${input.page_slug ? 'source_markdown_slug=$4' : `($4::text IS NULL AND NOT ${onOwnedMemoryPageSql('facts')})`}
    ORDER BY id DESC LIMIT 1`, [sourceId, input.visibility, input.fact, input.page_slug ?? null]);
  return row ? Number(row.id) : null;
}

/** Every retry renders the semantic append from the latest coherent snapshot. */
export async function prepareMemoryMutation(engine: BrainEngine, row: WriteRequest, config: GBrainConfig, signal?: AbortSignal, clock?: ClaimPhaseClock): Promise<PreparedMutation> {
  signal?.throwIfAborted();
  if (row.operation !== 'remember' || !row.intent) {
    throw opError('storage_error', 'Unknown memory mutation intent.',
      `Request ${row.request_id} in source ${row.source_id} carries no remember intent, so the coordinator cannot apply it and nothing was saved. This is an internal fault: inspect the request, then report it to the user.`,
      { fix: requestReceiptFix(row) });
  }
  const p = row.intent;
  // GST-2249 W1: a stored save made for an attested person never publishes shared, whenever it was admitted. An audience
  // (on_behalf_of) is not an attested person, so a shared agent's share: true still publishes.
  if (p.share === true && parseStoredActor(row.authority?.actingFor)) throw attestedShareRefused(opError);
  const claim = storedClaim(p);
  const input: SingleFactIntent = { fact: String(p.fact).trim(), kind: (p.kind ?? 'fact') as SingleFactIntent['kind'],
    visibility: (p.visibility ?? 'world') as SingleFactIntent['visibility'], entity_slug: p.entity_slug as string | null,
    ...(p.member_page === true || p.scope_page === true ? { page_slug: row.slug } : {}),
    ...(claim ? { slot: { ...claim, valid_from: String(p.valid_from) } } : {}) };
  const snapshot = await engine.readPageSnapshot(row.slug, { sourceId: row.source_id, includeDeleted: true });
  if ((snapshot?.page.id ?? null) !== row.page_id && !rememberAcceptsPageCreatedSince(row, snapshot)) throw pageIdentityError(snapshot != null || row.page_id === null, 'The accepted entity was deleted or recreated.');
  if (p.member_page === true && snapshot && !memberPageIsOwn(row.slug, snapshot.page.frontmatter)) throw memberPageNotOwned(row.slug);
  if (p.scope_page === true && snapshot && !await scopePageIsShared(engine, { ...withoutBody(snapshot.page), source_id: row.source_id, slug: row.slug })) throw scopePageNotShared(row.source_id);
  // A defaulted visibility never lands broader than the target page as it stands at publication.
  if (p.visibility_defaulted === true && snapshot) input.visibility = tightenToPage(input.visibility, await withFolderRestricted(engine, snapshot.page));
  // GST-2243: a shared fact whose page turned restricted after admission is refused, never saved private under a world receipt.
  if (p.share === true && input.visibility !== 'world') {
    throw Object.assign(opError('invalid_params', `remember: share: true cannot share a fact on ${row.slug}, whose facts are now kept private; nothing was saved.`,
      'Share it on a page every reader of this source can read, or drop share to keep the fact on your own page.'), { reason: 'share_target_restricted' });
  }
  if (p.expected_revision !== undefined) assertPageRevision(snapshot, engineMutationPrecondition(parseMutationPrecondition(p)));
  const observedRevision = snapshot?.revision ?? null;
  const excludePrivate = await resolveExcludePrivatePages(engine, row.authority.remote === true);
  await assertFactNotWithdrawn(engine, row.source_id, input, { excludePrivate, remote: row.authority.remote === true });
  signal?.throwIfAborted();
  const embeddingConfigSql = "SELECT key,value FROM config WHERE key IN ('embedding_model','embedding_dimensions') ORDER BY key";
  const observedEmbeddingConfig = JSON.stringify(await engine.executeRaw(embeddingConfigSql));
  const { embedding, embedding_model, degraded } = await prepareFactEmbedding(input.fact, signal, await factEmbeddingDisabled(engine, config), clock?.deadlineAt);
  signal?.throwIfAborted();
  // #5836: an inferred link dedups exact text only, so it never supersedes or drops a similar fact.
  const dedupEmbedding = p.entity_inferred ? null : embedding;
  // `replaces`: the caller names the fact this one replaces (checked; the cosine rule does not apply).
  const replaces = p.replaces !== undefined && p.replaces !== null ? Number(p.replaces) : null;
  const replace = (e: BrainEngine, target: number, lock: boolean) =>
    decideReplacement(e, row.source_id, input, target, { pageSlug: row.slug, remote: row.authority.remote === true, lock, excludePrivate, slugPrefixes: row.authority.slugPrefixes });
  const decideClaim = async (e: BrainEngine, lock = false) => {
    if (replaces !== null) return replace(e, replaces, lock);
    // The same claim saved earlier without an entity is this fact unlinked: linking it supersedes that copy,
    // so no subjectless duplicate is left whose forget would withdraw the claim from every entity.
    const unlinked = input.entity_slug === null ? null : await activeUnlinkedCopy(e, row.source_id, input, excludePrivate);
    if (unlinked !== null) {
      const linked = await replace(e, unlinked, lock).catch(() => null);
      if (linked) return linked;
    }
    return decideSingleFact(e, row.source_id, input, dedupEmbedding, embedding_model, undefined, { excludePrivate });
  };
  // A typed claim on a saved copy of the same claim that has none supersedes that copy, so the claim is kept (never dropped as a duplicate).
  const decide = async (e: BrainEngine, lock = false) => {
    const d = await decideClaim(e, lock);
    return claim && d.status === 'duplicate' && !storedClaim(d.candidate) ? { ...d, status: 'superseded' as const } : d;
  };
  const decision = await decide(engine);
  // #5575 I3: a lower-tier write never supersedes; it is inserted contested and the owner decides (re-checked under lock by validate).
  const writerTier = requestChannelTrust(row)?.tier ?? 'unknown';
  const contested = decision.status === 'superseded' && supersessionGuarded(writerTier, decision.candidate!.trust_tier);
  // GST-2897 B: a member's share about another member (submitRememberMutation records the member) is stored private and
  // supersedes nothing until the brain owner confirms it.
  const heldFor = p.share === true && typeof p.share_held === 'string' && input.visibility === 'world' ? p.share_held : null;
  const status = contested || heldFor ? 'inserted' : decision.status;
  // Without a fact vector the slot has no cosine; a lexical same-subject match still contests a more trusted fact (never supersedes).
  const lexical = (tx: BrainEngine) => decision.status === 'inserted' && !dedupEmbedding && replaces === null ? lexicalContestCandidate(tx, row.source_id, input, writerTier) : Promise.resolve(null);
  const lexicalOld = await lexical(engine);
  const contestedOld = contested ? decision.candidate! : lexicalOld;
  // GST-2875: a world write restating a more trusted private claim is stored private; its proposal carries the widening.
  const restated = (tx: BrainEngine) => decision.status !== 'duplicate' && input.visibility === 'world' ? restatedPrivateCopy(tx, row.source_id, input.fact, input.entity_slug, writerTier) : Promise.resolve(null);
  const restatedOld = await restated(engine);
  const widening = restatedOld ? { from: restatedOld.visibility, to: 'world' } : heldFor ? { from: 'private', to: 'world' } : null;
  const validate = async (tx: BrainEngine) => {
    await assertFactNotWithdrawn(tx, row.source_id, input, { excludePrivate, remote: row.authority.remote === true });
    if (embedding && JSON.stringify(await tx.executeRaw(`${embeddingConfigSql} FOR SHARE`)) !== observedEmbeddingConfig) conflict(row);
    const current = await decide(tx, true);
    if (candidateState(current) !== candidateState(decision)) conflict(row);
    if ((await lexical(tx))?.id !== lexicalOld?.id) conflict(row);
    if ((await restated(tx))?.id !== restatedOld?.id) conflict(row);
  };
  if (decision.status === 'duplicate') {
    const duplicate = decision.candidate!;
    return { observedRevision, noop: true, validate, apply: async () => ({ ...outcome(duplicate.id, 'duplicate', input.entity_slug, duplicate.valid_until, degraded, p), ...claimColumns(duplicate),
      ...(claim && JSON.stringify(storedClaim(duplicate)) !== JSON.stringify(claim) ? { claim_ignored: 'existing_claim' } : {}) }) };
  }
  const validUntil = p.valid_until ? new Date(String(p.valid_until)) : null;
  const validFrom = new Date(String(p.valid_from));
  const context = p.entity_inferred ? appendContextNote(null, inferenceNote(p.entity_inferred as InferredVia)) : undefined;
  const fact: NewFact & { valid_from: Date } = { ...input, source: String(p.provenance).trim(), valid_from: validFrom, valid_until: validUntil,
    confidence: 1, embedding, embedding_model, source_session: typeof p.session_id === 'string' ? p.session_id : null,
    ...(context ? { context } : {}), ...claimColumns(p) };
  // #5575 B3: the row-level write gate at the request's declared tier (ENG-18); a held fact inserts nothing.
  const gate = decideFactWrite({ fact: input.fact, context: context ?? null, source: fact.source }, { sourceId: row.source_id, slug: row.slug,
    payload: { fact: input.fact, kind: input.kind, visibility: input.visibility, entity_slug: input.entity_slug, source: fact.source, context: context ?? null,
      valid_from: validFrom.toISOString(), valid_until: validUntil?.toISOString() ?? null, source_session: fact.source_session, ...claimColumns(p) },
    input: gateInput(requestChannelTrust(row) ?? { tier: 'unknown', origin: null }, row.id), cfg: await loadWriteGateConfig(engine) });
  if (gate.action === 'reject') throw writeGateRejectedError(gate.assessment);
  if (gate.action === 'hold') return { observedRevision, noop: true, validate, apply: async tx => heldOutcome(gate.assessment, (await recordWriteGateHold(tx, gate.hold!)).holdId) };
  const retiredUntil = status === 'superseded' ? supersededValidUntil(decision.candidate!, validFrom) : null;
  // The fact is published as a row of its entity page's facts fence, file before facts row (facts/fence-fact-append.ts).
  let fence: FenceFactAppend | undefined;
  if (p.fence === true && (snapshot || isHoldingSlug(row.slug))) {
    const old = decision.candidate;
    fence = await prepareFenceFactAppend(engine, row, config, snapshot, { fact, pendingTier: fenceAppendPendingTier(writerTier), ...(widening ? { storedVisibility: widening.from } : {}),
      supersede: status === 'superseded' && old?.source_markdown_slug === row.slug && old.row_num != null ? { rowNum: Number(old.row_num), validUntil: retiredUntil } : undefined }, signal);
  } else if (p.fence === true && p.member_page === true) {
    fence = await prepareFenceFactCreate(engine, row, config, { fact, pendingTier: fenceAppendPendingTier(writerTier), ...(widening ? { storedVisibility: widening.from } : {}),
      frontmatter: memberPageFrontmatter(row.slug.slice(MEMBER_PAGE_PREFIX.length)), heading: `# Memory of ${row.slug.slice(MEMBER_PAGE_PREFIX.length)}` }, signal);
  } else if (p.fence === true && p.scope_page === true) {
    fence = await prepareFenceFactCreate(engine, row, config, { fact, pendingTier: fenceAppendPendingTier(writerTier), ...(widening ? { storedVisibility: widening.from } : {}),
      frontmatter: scopePageFrontmatter(), heading: '# Scope memory' }, signal);
  }
  // GBRA-190 G4: linking a fact saved without an entity retires its holding row in the same publication.
  const old = status === 'superseded' ? decision.candidate! : null;
  const linkedRow = old && isHoldingSlug(old.source_markdown_slug) && row.slug !== old.source_markdown_slug && old.row_num != null
    ? await prepareFenceRowRetirement(engine, row, config, old.source_markdown_slug!, { rowNum: Number(old.row_num), note: `linked to ${input.entity_slug}`, validUntil: retiredUntil }, signal) : null;
  // The belief ledger records the superseded fact in its own stream, so that stream's page key is held too.
  const supersededStream = status === 'superseded' ? decision.candidate!.source_markdown_slug ?? decision.candidate!.entity_slug ?? null : null;
  const additionalPageKeys = supersededStream && supersededStream !== row.slug && !linkedRow ? [{ sourceId: row.source_id, slug: supersededStream }] : undefined;
  const page = fence?.prepared ?? undefined;
  return { observedRevision, file: page?.file, ...(page?.exclusiveSources ? { exclusiveSources: page.exclusiveSources } : {}), ...(additionalPageKeys ? { additionalPageKeys } : {}),
    ...(linkedRow ? { companions: [linkedRow] } : {}), validate: async tx => { await validate(tx); await page?.validate?.(tx); }, apply: async tx => {
    let id: number;
    let pageReceipt: { size_state?: unknown } | undefined;
    if (fence) {
      ({ id, pageReceipt } = await fence.apply(tx));
    } else {
      const inserted = await tx.insertFact(widening ? { ...fact, visibility: widening.from as NewFact['visibility'] } : fact, { source_id: row.source_id }); // gbrain-allow-direct-insert: journaled source-scoped semantic publication for subjectless or unresolved entity memory
      id = inserted.id;
    }
    if (status === 'superseded') {
      await tx.executeRaw(`UPDATE facts SET expired_at=now(),superseded_by=$3,valid_until=COALESCE($4::timestamptz,valid_until)
      WHERE id=$1 AND source_id=$2 AND expired_at IS NULL`, [decision.candidate!.id, row.source_id, id, retiredUntil]);
      noteBelief({ kind: 'superseded', oldId: Number(decision.candidate!.id), newId: id });
    }
    const contestedBy = contestedOld ? await recordContestedFact(tx, { sourceId: row.source_id, oldId: contestedOld.id,
      oldTier: storedTrustTier(contestedOld.trust_tier), newId: id, newTier: writerTier,
      guard: replaces !== null ? 'remember.replaces' : contested ? 'conflict_slot' : 'conflict_slot_lexical',
      ...(widening && restatedOld?.id === contestedOld.id ? { visibility: widening, pageless: !fence } : {}) }) : null;
    const widenedBy = restatedOld && restatedOld.id !== contestedOld?.id ? await recordContestedFact(tx, { sourceId: row.source_id, oldId: restatedOld.id,
      oldTier: restatedOld.trust_tier, newId: id, newTier: writerTier, guard: 'remember.restated_private', visibility: widening!, pageless: !fence }) : null;
    const held = heldFor && !restatedOld ? await recordHeldShare(tx, { sourceId: row.source_id, factId: id, tier: writerTier, member: heldFor, pageless: !fence }) : null;
    const flagged = gateField(gate.assessment, `f${id}`, await recordFlaggedRow(tx, gate, { table: 'facts', id, sourceId: row.source_id }));
    const superseded = status === 'superseded' ? decision.candidate! : undefined;
    return { ...outcome(id, status, input.entity_slug, validUntil, degraded, p, superseded?.id,
      superseded !== undefined && superseded.entity_slug == null && input.entity_slug !== null), ...claimColumns(p), ...fence?.fencesNormalized,
      ...(contestedBy ?? widenedBy ? { contested: contestedBy ?? widenedBy } : {}), ...(flagged ? { gate: flagged } : {}),
      ...(held ? { status_text: `held as fact #${id}: it is about member ${held.member}, so it stays private until the brain owner shares it (gbrain trust confirm ${held.proposal_ref})`, held } : {}),
      ...(pageReceipt?.size_state ? { size_state: pageReceipt.size_state } : {}) };
  } };
}