Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
59.2 KB
Raw Blame
/**
 * MEMORY_VERBS v1 — the frozen memory protocol verbs (Cathedral 1).
 *
 * Four first-class Operations (`remember`, `entity`, `synthesize`, `forget`)
 * that join the extended `recall` op (operations.ts) as the five-verb façade
 * over the operation catalog. Frozen contract: docs/protocol/MEMORY_VERBS_v1.md
 * — field names and semantics in v1 never change; additions are forever-
 * additive; `protocol_version` rides every response; errors carry enumerated
 * codes + populated `suggestion` (agents read it and self-correct).
 *
 * These are ordinary Operations: they inherit trust-boundary fail-closed
 * semantics (ctx.remote), scope enforcement, and source isolation like every
 * other op. `gbrain serve --surface verbs` exposes exactly the ops marked
 * `verb: true`.
 *
 * Import-cycle note: operations.ts spreads these into its `operations` array
 * at MODULE-EVAL time, so this file must be a RUNTIME LEAF — it may import
 * operations.ts types (erased) but never its values statically. Handlers load
 * verbError/parseTtlParam/sourceScopeOpts via dynamic import from the ops
 * modules that define them (never the whole operations.ts registry, which a
 * one-shot CLI call would otherwise evaluate in full, #7147); the import
 * resolves after both modules finish evaluating.
 * MEMORY_VERBS_VERSION lives HERE (operations.ts imports it from us) for the
 * same reason. Violating this reintroduces the TDZ crash on whichever module
 * evaluates second.
 */

import { recordFunnelEvent, recordRememberOutcome } from './funnel.ts';
import type { Operation } from './operations.ts';
import { WRITE_RECEIPT_SCHEMA, WRITE_REQUEST_PARAM, AGENT_CONTENT_PARAMS, CONTENT_ORIGIN_PARAM } from './persistence/params.ts';
import { WRITE_ERROR_CODES } from './persistence/types.ts';
import { isStrictIsoDateTime } from './utils.ts';

/** Frozen protocol version for the MEMORY_VERBS v1 verb set. Single source of truth. */
export const MEMORY_VERBS_VERSION = 1;

// v0.45.7 (issue #1): the frozen set grows from 5 to 7 with two ambient-recall
// verbs. The wire protocol_version STAYS 1 (additive) — MEMORY_VERBS_VERSION is
// unchanged so the five existing schemas + handlers keep stamping 1 and their
// conformance assertions (protocol_version === 1) hold.
export const VERB_NAMES = ['recall', 'remember', 'entity', 'synthesize', 'forget', 'context_pack', 'delta'] as const;
export type VerbName = (typeof VERB_NAMES)[number];

/**
 * The `remember` INPUT enum — FROZEN at five by the v1 protocol contract
 * (docs/protocol/MEMORY_VERBS_v1.md: "the values and their meanings stay
 * fixed"). Widening the extractor/DB taxonomy does NOT widen this; a caller
 * cannot write an `idea` through the verb surface.
 */
const FACT_KINDS = ['event', 'preference', 'commitment', 'belief', 'fact'] as const;

/**
 * What a reader may RECEIVE. The extractor and the facts table carry `idea`
 * (migration v145), so a stored idea fact flows back through `recall` — a
 * response schema that omitted it would declare a contract the system itself
 * violates. This is a widening for response consumers (strictly more values
 * accepted), and it is deliberately a SEPARATE constant so the input freeze
 * above can never drift into it.
 */
const FACT_KINDS_RESPONSE = [...FACT_KINDS, 'idea'] as const;
const PROVENANCE_MAX = 500;
const REMEMBER_CALL_SHAPE = 'A valid call: {"fact": "<one claim>", "entity": "<subject-slug>", "provenance": "<where you learned it, with the date>"}; several: items: [{fact, entity, provenance}, ...]. provenance (where the fact came from) is required.';

// ─── remember ────────────────────────────────────────────────────────────────

const remember: Operation = {
  name: 'remember',
  idempotent: true,
  outputRedaction: 'no_stored_text',
  description: 'Save {fact, provenance (required), `entity` (subject; recall needs it)} or items[]. Branch on `status`; write_pending: poll get_write_request.',
  callShape: REMEMBER_CALL_SHAPE,
  params: {
    ...AGENT_CONTENT_PARAMS,
    fact: { type: 'string', description: 'One claim.' },
    items: {
      type: 'array',
      description: '≤20 of {fact,entity,provenance,kind,ttl,visibility}',
      items: { type: 'object' },
    },
    provenance: {
      type: 'string',
      // Required for a single fact (the handler refuses with provenance_required); with items it may be given per item.
      description: 'Source (≤500 chars).',
    },
    ttl: {
      type: 'string',
      description: '"30d", "12h", ISO; omit = never.',
    },
    valid_from: {
      type: 'string',
      description: 'When true (ISO).',
      fullSurfaceOnly: true,
    },
    entity: {
      type: 'string',
      description: 'Name or slug.',
    },
    infer_entity: {
      type: 'boolean',
      description: 'Default true.',
      fullSurfaceOnly: true,
    },
    kind: {
      type: 'string', description: 'Default fact.',
      enum: [...FACT_KINDS],
    },
    share: {
      type: 'boolean',
      description: 'Members save privately, owner shared; true: all source readers recall it. Not for facts about a person.',
    },
    visibility: {
      type: 'string',
      enum: ['world', 'private'],
      description: 'world (default) or private (local CLI). Members: use share.',
      fullSurfaceOnly: true,
    },
    replaces: { type: 'string', description: 'fact_id this fact replaces (same entity, or none).', fullSurfaceOnly: true },
    claim_metric: { type: 'string', description: 'Typed claim metric, e.g. mrr (with claim_value).', fullSurfaceOnly: true },
    claim_value: { type: 'number', description: 'Typed claim value (finite number).', fullSurfaceOnly: true },
    claim_unit: { type: 'string', description: 'Typed claim unit, e.g. USD.', fullSurfaceOnly: true },
    claim_period: { type: 'string', description: 'Typed claim period, e.g. monthly.', fullSurfaceOnly: true },
  },
  mutating: true,
  scope: 'write',
  verb: true,
  annotations: { title: 'remember (memory write)', idempotentHint: true },
  handler: async (ctx, p) => {
    const [{ verbError }, { parseTtlParam }] = await Promise.all([import('./ops/contract.ts'), import('./ops/facts.ts')]);
    if (p.items !== undefined) {
      const { runRememberBatch } = await import('./remember-batch.ts');
      return runRememberBatch(ctx, p, remember.handler, (code, message, suggestion) => verbError(code as never, message, suggestion));
    }
    const { unquoteFactText } = await import('./search/transcript-quote.ts');
    // #8377: a fact an agent copied out of a quoted read (recall, context_pack, hot memory) is stored without the fence.
    const fact = typeof p.fact === 'string' ? (ctx.remote === false ? p.fact : unquoteFactText(p.fact)).trim() : '';
    if (!fact) {
      throw verbError(
        'invalid_params',
        'fact must be a non-empty string.',
        p.fact === undefined && Object.keys(p).length === 0
          ? 'The call arrived with no arguments; a tool call cut off at your output-token limit looks like this. Pass fact, or items with fewer entries per call.'
          : `Pass the claim to remember in fact. ${REMEMBER_CALL_SHAPE}`,
      );
    }
    // v1 contract: an absent provenance is a missing required parameter (invalid_params), an empty one is provenance_required.
    if (p.provenance === undefined) {
      throw verbError(
        'invalid_params',
        'Missing required parameter: provenance',
        'Pass `provenance` as a string (where the fact came from), e.g. provenance: "<where you learned it, with the date>". With items, provenance may be given per item instead.',
      );
    }
    const provenance = typeof p.provenance === 'string' ? p.provenance.trim() : '';
    if (!provenance) {
      throw verbError(
        'provenance_required',
        'provenance is required and must be non-empty.',
        'Pass where the fact came from, e.g. provenance: "<where you learned it, with the date>" or "import: notes.md".',
      );
    }
    if (provenance.length > PROVENANCE_MAX) {
      throw verbError(
        'invalid_params',
        `provenance exceeds ${PROVENANCE_MAX} chars (got ${provenance.length}).`,
        'Shorten the attribution — provenance is a pointer, not a transcript.',
      );
    }
    const kind = typeof p.kind === 'string' ? p.kind : 'fact';
    if (!FACT_KINDS.includes(kind as (typeof FACT_KINDS)[number])) {
      throw verbError(
        'invalid_params',
        `kind "${kind}" is not a fact kind.`,
        `Use one of: ${FACT_KINDS.join(' | ')}.`,
      );
    }
    const visibility = typeof p.visibility === 'string' ? p.visibility : 'world';
    if (visibility !== 'world' && visibility !== 'private') {
      throw verbError(
        'invalid_params',
        `visibility "${visibility}" is not valid.`,
        'Use "world" (default — agents can recall it) or "private" (local CLI reads only).',
      );
    }
    if (p.share !== undefined && typeof p.share !== 'boolean') {
      throw verbError('invalid_params', 'share must be true or false.', 'Pass share: true to save the fact for everyone who reads this source, or omit it.');
    }
    if (p.share === true && p.visibility === 'private') {
      throw verbError('invalid_params', 'share: true and visibility "private" contradict each other; nothing was saved.', 'Pass share: true to share the fact, or visibility "private" to keep it to yourself, not both.');
    }
    // GST-2249 W1: a save made for a person (x-qm-actor) stays on that person's member page; sharing it is a write every
    // reader of the source sees, made with no owner approval, so it is refused like the direct page writes.
    const memberFacts = await import('./access/member-facts.ts');
    const attested = ctx.attestedOp !== 'memory_write' && (await import('./search/private-visibility.ts')).currentCallerAccess().actor != null;
    if (attested && p.share === true) throw memberFacts.attestedShareRefused(verbError);
    // GST-2243: a member shares only with share: true, so its explicit visibility "world" is refused, never quietly made private.
    // GST-2346 D1: the brain owner speaking for itself is not refused; its "world" is saved shared.
    if (p.share !== true && p.visibility === 'world' && ctx.attestedOp !== 'memory_write' && memberFacts.memberFactPage(ctx) && !memberFacts.ownerSpeaksForItself(ctx)) {
      if (attested) throw memberFacts.attestedShareRefused(verbError);
      // GST-2897 B: a fact about another member is never pointed at share: true, which holds it for the brain owner.
      const subject = typeof p.entity === 'string' ? await memberFacts.otherMemberSubject(ctx.engine, p.entity.trim()) : null;
      if (subject) {
        throw Object.assign(verbError('invalid_params', 'remember: a member credential cannot save a fact with visibility "world"; nothing was saved.',
          `${p.entity} is about member ${subject}. Retry with no visibility to keep the fact on your own member page; a shared fact about another member is held private until the brain owner confirms it.`),
          { reason: 'member_share_required' });
      }
      throw Object.assign(verbError('invalid_params', 'remember: a member credential shares a fact with share: true, not visibility "world"; nothing was saved.',
        'Retry the same call with share: true in place of visibility "world" to share a fact about the team\'s work with everyone who reads this source, or with no visibility to keep a fact about a person on your own member page. A member shares only this way: pass share: true, never visibility "world".'),
        { reason: 'member_share_required' });
    }
    if (p.valid_from !== undefined && !isStrictIsoDateTime(p.valid_from)) {
      throw verbError(
        'invalid_params',
        'valid_from must be an ISO 8601 date or time in years 0001-9999.',
        'Pass when the fact was said or became true as YYYY-MM-DD or YYYY-MM-DDTHH:MM[:SS][Z|±HH:MM], e.g. valid_from: "2026-03-01", or omit it.',
      );
    }
    const claim = (await import('./facts/typed-claim.ts')).parseClaimParams(ctx.remote === false ? p : { ...p,
      ...Object.fromEntries((['claim_metric', 'claim_unit', 'claim_period'] as const).flatMap(k => typeof p[k] === 'string' ? [[k, unquoteFactText(p[k] as string)]] : [])) });
    if (p.content_origin !== undefined && !CONTENT_ORIGIN_PARAM.enum!.includes(p.content_origin as string)) {
      throw verbError('invalid_params', `content_origin must be one of ${CONTENT_ORIGIN_PARAM.enum!.join(', ')}; got ${JSON.stringify(p.content_origin)}.`,
        'Pass content_origin as user_said, tool_output (text from a web page, email, file or other tool) or inferred, or omit it.');
    }
    const replaces = typeof p.replaces === 'string' ? p.replaces.trim() : typeof p.replaces === 'number' ? String(p.replaces) : undefined;
    if (replaces !== undefined && (!/^\d+$/.test(replaces) || Number(replaces) <= 0)) {
      throw verbError(
        'not_found',
        `No fact with id "${String(p.replaces)}" to replace.`,
        'Pass the opaque fact_id from remember or recall (facts[].fact_id), or omit replaces.',
      );
    }
    if (ctx.dryRun) {
      parseTtlParam(p.ttl); // Dry runs still validate without admitting intent.
      return {
        dry_run: true,
        action: 'remember',
        fact,
        protocol_version: MEMORY_VERBS_VERSION,
      };
    }

    const { submitRememberMutation } = await import('./persistence/memory-mutations.ts');
    const { runMemoryWrite } = await import('./persistence/verb-errors.ts');
    const result = await runMemoryWrite(() => submitRememberMutation(ctx, { ...p, fact, provenance, kind, visibility, ...claim, ...(replaces !== undefined ? { replaces } : {}) },
      undefined, { visibilityDefaulted: typeof p.visibility !== 'string' }));
    // F8: the explanation the CLI formatter prints, as a model-visible notice.
    if ((result as { degraded_dedup?: boolean } | null)?.degraded_dedup) {
      const { degradedDedupNotice } = await import('./interop-notices.ts');
      ctx.emitNotice?.(degradedDedupNotice(ctx.config));
    }
    if (visibility === 'private' && ctx.remote === false && (result as { status?: string } | null)?.status !== 'duplicate') {
      const { privateFactNotice } = await import('./interop-notices.ts');
      ctx.emitNotice?.(privateFactNotice((result as { id?: string | number } | null)?.id));
    }
    recordRememberOutcome(result);
    return result;
  },
  cliHints: { name: 'remember', positional: ['fact'] },
};

// ─── entity ──────────────────────────────────────────────────────────────────

const entity: Operation = {
  name: 'entity',
  mutating: false,
  idempotent: true,
  outputRedaction: 'retrieval',
  description: 'Person/company/account card, zero LLM. Previews are not evidence: fetch the page before stating status or dates. Miss: found:false with near matches (create_safety). Facts: recall.',
  params: {
    name: { type: 'string', description: 'Name, alias or slug.' },
    names: { type: 'array', items: { type: 'string' }, description: 'Or up to 50 names/codes at once: compact rows.' },
    source_id: { type: 'string', description: 'Read only this source. Default: your source first, then every source you can read.', fullSurfaceOnly: true },
    prefer_source_id: { type: 'string', description: 'Source to try first (thin clients send .gbrain-source here); never narrows.', fullSurfaceOnly: true },
    variants: { type: 'boolean', description: 'false: exact names only. Default true: with no exact match, one unambiguous name variant (card.match says which).', fullSurfaceOnly: true },
  },
  scope: 'read',
  verb: true,
  annotations: { title: 'entity (card lookup, zero LLM)', readOnlyHint: true },
  handler: async (ctx, p) => {
    const { verbError } = await import('./ops/contract.ts');
    // #6723: resolve across the caller's readable sources (home first) unless source_id pins one.
    const { ambientMissNotice, entitySources } = await import('./verbs/entity-source.ts');
    const walk = await entitySources(ctx, p, 'entity');
    const ambientMiss = (misses: Array<{ name: string; foundIn?: string }>) => {
      const notice = ambientMissNotice('entity', walk, misses.filter(m => m.foundIn !== walk.ambient?.sourceId));
      if (notice) ctx.emitNotice?.(notice);
    };
    if (p.names !== undefined) {
      const { ENTITY_NAMES_MAX, lookupEntityNames } = await import('./verbs/entity-names.ts');
      const names = Array.isArray(p.names) ? p.names.filter((n): n is string => typeof n === 'string' && n.trim() !== '') : [];
      if (p.name !== undefined || !names.length || names.length > ENTITY_NAMES_MAX) {
        throw verbError('invalid_params', `names must be 1 to ${ENTITY_NAMES_MAX} non-empty strings, without name.`,
          `Pass either name: "Alice Example" for one full card, or names: ["Alice Example", "WGCO"] (up to ${ENTITY_NAMES_MAX}) for compact rows.`);
      }
      const t0 = Date.now();
      const out = await lookupEntityNames(ctx.engine, walk.home, names, { remote: ctx.remote !== false, sources: walk.sources, surfaceCeiling: ctx.surfaceCeiling, variants: p.variants !== false,
        emitNotice: n => ctx.emitNotice?.(n) });
      ambientMiss(out.results.map(r => ({ name: r.name, ...(r.found ? { foundIn: r.source_id } : {}) })));
      return { protocol_version: 1, latency_ms: Date.now() - t0, ...out };
    }
    const name = typeof p.name === 'string' ? p.name.trim() : '';
    if (!name) {
      throw verbError(
        'invalid_params',
        'name must be a non-empty string.',
        'Pass the entity to look up, e.g. name: "Alice Example" or name: "people/alice-example".',
      );
    }
    const t0 = Date.now();
    const { buildEntityCard } = await import('./verbs/entity-card.ts');
    const result = await buildEntityCard(ctx.engine, walk.home, name, {
      remote: ctx.remote !== false, includeReferences: true, surfaceCeiling: ctx.surfaceCeiling, sources: walk.sources, variants: p.variants !== false,
      omitQuarantined: ctx.remote !== false, // #5575: like get_page, a remote reader never gets a quarantined page's card
      emitNotice: n => ctx.emitNotice?.(n),
    });
    const coverage = result.card?.coverage ?? result.coverage;
    if (coverage) {
      const { mentionCoverageNotice } = await import('./mentions/coverage.ts');
      const notice = mentionCoverageNotice(coverage, result.card?.entity.type);
      if (notice) ctx.emitNotice?.(notice);
    }
    ambientMiss([{ name, ...(result.source_id ? { foundIn: result.source_id } : {}) }]);
    if (result.card?.identity_siblings?.capped) {
      const { siblingsCappedNotice } = await import('./verbs/entity-card-identity.ts');
      ctx.emitNotice?.(siblingsCappedNotice(result.card.entity.slug));
    }
    return {
      protocol_version: MEMORY_VERBS_VERSION,
      found: result.found,
      latency_ms: Date.now() - t0,
      ...(result.card ? { card: result.card } : {}),
      ...(result.suggestions !== undefined ? { suggestions: result.suggestions } : {}),
      ...(!result.card && result.coverage ? { coverage: result.coverage } : {}),
      ...(result.text_mentions ? { text_mentions: result.text_mentions } : {}),
      ...(result.ambiguous ? { ambiguous: true } : {}),
    };
  },
  cliHints: { name: 'entity', positional: ['name'] },
};

// ─── synthesize ──────────────────────────────────────────────────────────────

// [WP2/T5] compose-failure status → the machine-stable warning code named in
// the empty-gather `unavailable` error message. Freeform tails (provider
// messages) ride `detail` only; the message carries the code.
const SYNTHESIS_FAILURE_CODES: Record<string, string> = {
  not_json: 'LLM_OUTPUT_NOT_JSON',
  output_truncated: 'LLM_OUTPUT_TRUNCATED',
  empty_answer: 'SYNTHESIS_EMPTY_ANSWER',
  llm_error: 'LLM_CALL_FAILED',
  model_unusable: 'MODEL_NOT_USABLE',
  no_llm: 'NO_ANTHROPIC_API_KEY',
};

const synthesize: Operation = {
  name: 'synthesize',
  mutating: false,
  idempotent: true,
  outputRedaction: 'retrieval',
  description: '[EXPENSIVE / SLOW: LLM calls] Cited answer to a broad question across pages. Lookups: recall or entity.',
  params: {
    question: { type: 'string', description: 'The question.', required: true },
    since: { type: 'string', description: 'Window start (ISO 8601).' },
    until: { type: 'string', description: 'Window end (ISO 8601).' },
  },
  scope: 'read',
  verb: true,
  annotations: { title: 'synthesize (slow, costly — LLM-backed)', readOnlyHint: true },
  handler: async (ctx, p) => {
    const [{ verbError }, { sourceScopeOpts }] = await Promise.all([import('./ops/contract.ts'), import('./ops/context.ts')]);
    const question = typeof p.question === 'string' ? p.question.trim() : '';
    if (!question) {
      throw verbError(
        'invalid_params',
        'question must be a non-empty string.',
        'Pass the question to synthesize an answer for, e.g. question: "what is our payments strategy?".',
      );
    }
    const scope = sourceScopeOpts(ctx);
    const { runThink } = await import('./think/index.ts');
    const { embedQueryWithPrefix } = await import('./search/query-prefix.ts');
    // Remote-safe delegation: save/take are NEVER offered through this verb,
    // for any caller — the verb is a pure read.
    const result = await runThink(ctx.engine, {
      question,
      since: p.since ? String(p.since) : undefined,
      until: p.until ? String(p.until) : undefined,
      takesHoldersAllowList: ctx.takesHoldersAllowList,
      ...(scope.sourceId !== undefined ? { sourceId: scope.sourceId } : {}),
      ...(scope.sourceIds !== undefined ? { allowedSources: scope.sourceIds } : {}),
      // Fail-closed: only a context that explicitly says local gets local.
      remote: ctx.remote !== false,
      // #3734: activate takes' vector retrieval arm for the synthesize verb.
      embedQuestion: (q) => embedQueryWithPrefix(ctx.engine, q),
    });

    // [c10] runThink degrades gracefully to a no-LLM stub RESULT; the protocol
    // contract converts that state into an explicit `unavailable` error so
    // agents branch on configure/retry instead of relaying a fake answer.
    // Deliberately unconditional (fires even with a non-empty gather): an
    // unconfigured key routed to the extractive fallback would be masked on
    // every call and never get fixed.
    if (result.warnings.includes('NO_ANTHROPIC_API_KEY')) {
      // F9: a key enables paid calls, so the fix asks; the key never rides a command line.
      const { chatKeyFix } = await import('./interop-notices.ts');
      const e = verbError(
        'unavailable',
        'synthesize needs an LLM and none is configured.',
        'Ask the user whether to add a chat-model API key (Anthropic or OpenAI; each synthesized answer is a paid call). Meanwhile recall and entity work without one: answer from their results.',
        'chat gateway unconfigured (NO_ANTHROPIC_API_KEY)',
      );
      e.fix = chatKeyFix();
      throw e;
    }

    // Best-effort cost block [E5/m3]: actual tokens when the gateway reported
    // usage, priced via the canonical table; nulls when accounting is absent.
    const { canonicalLookup } = await import('./model-pricing.ts');
    const usage = result.usage ?? null;
    const pricing = canonicalLookup(result.modelUsed);
    const usdEstimate =
      usage && pricing
        ? (usage.input_tokens * pricing.input + usage.output_tokens * pricing.output) / 1_000_000
        : null;
    const cost = {
      model: result.modelUsed,
      input_tokens: usage?.input_tokens ?? null,
      output_tokens: usage?.output_tokens ?? null,
      usd_estimate: usdEstimate,
    };

    // [WP2/T5+E2] compose-status precedence: 'ok' → the synthesized answer;
    // any compose failure with a NON-EMPTY gather → the extractive fallback
    // (quotes/cites ONLY gathered pages); compose failure with an EMPTY
    // gather → typed error. An answer is NEVER fabricated from nothing
    // (ENG-19). Defensive ?? 'ok' mirrors synthesisOk's back-compat posture.
    const status = result.synthesis_status ?? 'ok';
    const { recordThinkAnswer, feedbackMetaFields } = await import('./feedback/record.ts');
    const feedbackMeta = feedbackMetaFields(await recordThinkAnswer(ctx, 'synthesize', result));
    if (status !== 'ok') {
      if (result.extractive) {
        return {
          answer: result.extractive.answer,
          sources: result.extractive.citations.map(c => c.page_slug),
          citations: sourceQualifiedCitations(result.extractive.citations),
          gaps: result.gaps,
          cost,
          synthesis_status: 'extractive_fallback',
          pages_gathered: result.pagesGathered,
          takes_gathered: result.takesGathered,
          evidence_truncated: result.evidence_truncated ?? false,
          warnings: result.warnings,
          ...feedbackMeta,
          protocol_version: MEMORY_VERBS_VERSION,
        };
      }
      throw verbError(
        'unavailable',
        `retrieved ${result.pagesGathered} pages; compose failed: ${SYNTHESIS_FAILURE_CODES[status] ?? status}`,
        'The LLM compose step failed and retrieval found nothing to fall back on. Rephrase or broaden the question (or the since/until window); if the code names the model or provider, fix the model config and retry.',
        result.warnings.length > 0 ? result.warnings.join('; ') : undefined,
      );
    }

    return {
      answer: result.answer,
      ...(result.answer_raw !== undefined ? { answer_raw: result.answer_raw, quote_check: result.quote_check, unverified_quotes: result.unverified_quotes } : {}),
      sources: result.citations.map(c => c.page_slug),
      citations: sourceQualifiedCitations(result.citations),
      gaps: result.gaps,
      cost,
      synthesis_status: 'ok',
      pages_gathered: result.pagesGathered,
      takes_gathered: result.takesGathered,
      evidence_truncated: result.evidence_truncated ?? false,
      warnings: result.warnings,
      ...feedbackMeta,
      protocol_version: MEMORY_VERBS_VERSION,
    };
  },
  cliHints: { name: 'synthesize', positional: ['question'] },
};

/** #5461: `sources[]` stays slugs (frozen); `citations[]` is the same list, source-qualified. */
function sourceQualifiedCitations(citations: Array<{ page_slug: string; row_num: number | null; source_id?: string | null }>) {
  return citations.map(c => ({ slug: c.page_slug, source_id: c.source_id ?? null, row_num: c.row_num }));
}

// ─── forget ──────────────────────────────────────────────────────────────────

const forget: Operation = {
  name: 'forget',
  idempotent: true,
  outputRedaction: 'no_stored_text',
  description: 'Expire a remembered fact by its fact_id (never a page slug). Idempotent; the audit trail is kept.',
  params: {
    request_id: WRITE_REQUEST_PARAM,
    id: { type: 'string', required: true, description: 'fact_id from remember or recall.' },
    reason: { type: 'string', description: 'Audit note (default "forgotten").' },
    semantic_review: { type: 'boolean', description: 'false: skip overnight rewording review.', fullSurfaceOnly: true },
  },
  mutating: true,
  scope: 'write',
  verb: true,
  annotations: { title: 'forget (expire a fact)', destructiveHint: true, idempotentHint: true },
  handler: async (ctx, p) => {
    const { verbError } = await import('./ops/contract.ts');
    const rawId = typeof p.id === 'string' ? p.id.trim() : typeof p.id === 'number' ? String(p.id) : '';
    const numericId = Number(rawId);
    if (!rawId || !Number.isInteger(numericId) || numericId <= 0) {
      throw verbError(
        'not_found',
        `No fact with id "${String(p.id)}".`,
        'Pass the opaque string id returned by remember or recall (facts[].fact_id) — page slugs are not fact ids.',
      );
    }
    const reason = typeof p.reason === 'string' && p.reason.trim() ? p.reason.trim() : null;

    if (ctx.dryRun) {
      return { dry_run: true, action: 'forget', id: rawId, protocol_version: MEMORY_VERBS_VERSION };
    }

    const { submitForgetMutation } = await import('./persistence/memory-mutations.ts');
    const { runMemoryWrite } = await import('./persistence/verb-errors.ts');
    const out = await runMemoryWrite(() => submitForgetMutation(ctx, 'forget', { ...p, id: rawId, ...(reason ? { reason } : {}) }));
    recordFunnelEvent('withdrawal');
    return out;
  },
  // NO cliHints: `gbrain forget` is a CLI_ONLY command (recall.ts runForget)
  // that dispatches BEFORE cliOps — a cliHint here would be silently
  // shadowed. The CLI surface for forgetting stays the existing command;
  // this verb is the MCP/protocol surface.
};

export const verbOperations: Operation[] = [remember, entity, synthesize, forget];

// ─── RESPONSE_SCHEMAS — the protocol's response-shape registry [c8] ─────────
//
// `Operation` carries input params only; response envelopes live HERE, hand-
// authored, and conformance validates LIVE responses against this registry so
// registry-vs-code drift is caught by the same fixtures that certify servers.
// Field names and semantics are FROZEN (additive-forever); enum values are
// part of the contract.

const EVIDENCE_ENUM = ['alias_hit', 'exact_title_match', 'high_vector_match', 'keyword_exact', 'weak_semantic'];
const CREATE_SAFETY_ENUM = ['exists', 'probable', 'unknown'];
const STATUS_ENUM = ['inserted', 'duplicate', 'superseded'];
// v0.45.x (WP2/T5+E2) — additive-forever. The verb emits 'ok' or
// 'extractive_fallback'; the remaining compose-failure values ride the
// non-verb `think` surface (the verb converts them to the extractive
// fallback or a typed `unavailable` error) and stay enum-listed so any
// v1 server emitting them validates.
const SYNTHESIS_STATUS_ENUM = [
  'ok', 'empty_answer', 'not_json', 'output_truncated', 'no_llm', 'model_unusable', 'llm_error', 'extractive_fallback',
];

/** `coverage` on entity cards and misses (mentions/coverage.ts). */
const COVERAGE_SCHEMA = {
  type: 'object',
  required: ['state', 'pending_pages', 'last_pass_at'],
  properties: {
    state: { type: 'string', enum: ['complete', 'pending', 'disabled', 'type_not_linkable', 'failed'] },
    pending_pages: { type: 'integer' },
    last_pass_at: { type: ['string', 'null'] },
    degraded: { type: 'boolean', const: true },
  },
} as const;

/** One `referenced_by` row (mentions/referrers.ts). */
const REFERENCE_ROW_SCHEMA = {
  type: 'object',
  required: ['slug', 'title', 'type', 'canonical_type', 'date', 'date_source', 'preview', 'trust_tier', 'origin'],
  properties: {
    slug: { type: 'string' }, title: { type: 'string' }, type: { type: ['string', 'null'] }, canonical_type: { type: 'string' },
    date: { type: ['string', 'null'] }, date_source: { type: 'string' }, preview: { type: 'string' },
    trust_tier: { type: 'string' }, origin: { type: 'string' }, unconfirmed: { type: 'boolean', const: true },
  },
} as const;

/** One record group (verbs/entity-references.ts): referring pages of an enrolled record type, newest page date first. */
const RECORD_GROUP_SCHEMA = {
  type: 'object',
  required: ['canonical_type', 'total', 'rows'],
  properties: {
    canonical_type: { type: 'string' },
    total: { type: 'integer' },
    rows: { type: 'array', items: { type: 'object', required: ['slug', 'title', 'date', 'date_source'], properties: {
      slug: { type: 'string' }, title: { type: 'string' }, date: { type: ['string', 'null'] }, date_source: { type: 'string' },
      page_status: { type: 'string' },
      amends: { type: 'array', items: { type: 'object', required: ['slug'], properties: { slug: { type: 'string' }, since: { type: 'string' } } } },
      supersedes: { type: 'array', items: { type: 'object', required: ['slug'], properties: { slug: { type: 'string' } } } },
    } } },
    capped: { type: 'string', enum: ['per_page', 'per_call'] },
    next: { type: 'object', required: ['tool', 'arguments'], properties: {
      tool: { type: 'string', const: 'get_backlinks' }, arguments: { type: 'object' }, requires_surface: { type: 'string', enum: ['starter'] } } },
  },
} as const;

const REFERENCES_UNAVAILABLE_SCHEMA = { type: 'string', enum: ['deadline', 'read_failed'] } as const;

const RECALL_BUDGET_ARM_SCHEMA = {
  type: 'object',
  required: ['candidates', 'kept', 'dropped', 'used'],
  properties: {
    candidates: { type: 'integer', minimum: 0, description: 'Authorized, filtered, limit-capped candidates before packing.' },
    kept: { type: 'integer', minimum: 0 },
    dropped: { type: 'integer', minimum: 0 },
    used: { type: 'integer', minimum: 0, description: 'Estimated tokens in retained evidence, excluding the JSON envelope.' },
  },
};

export const RESPONSE_SCHEMAS: Record<VerbName, Record<string, unknown>> = {
  recall: {
    type: 'object',
    required: ['facts', 'total', 'protocol_version'],
    properties: {
      protocol_version: { type: 'integer', const: MEMORY_VERBS_VERSION },
      total: { type: 'integer' },
      facts: {
        type: 'array',
        items: {
          type: 'object',
          required: ['id', 'fact', 'kind', 'fact_id', 'provenance'],
          properties: {
            id: { type: 'integer', description: 'LEGACY numeric id (pre-v1 consumers). Use fact_id.' },
            fact_id: { type: 'string', description: 'Opaque protocol id — the value forget accepts.' },
            fact: { type: 'string' },
            kind: { type: 'string', enum: FACT_KINDS_RESPONSE as unknown as string[] },
            entity_slug: { type: ['string', 'null'] },
            provenance: { type: 'string' },
            valid_until: { type: ['string', 'null'] },
            visibility: { type: 'string', enum: ['private', 'world'] },
            relevance: { type: 'number', description: 'Present when `question` was passed: cosine + term share + 0.1 when dated (about 0 to 2.1). A ranking score within this response, not a probability; not comparable across calls.' },
          },
        },
      },
      facts_order: { type: 'string', enum: ['relevance', 'newest'], description: 'How facts[] is ordered: relevance (question passed) or newest. A server without question ranking omits it.' },
      facts_degraded: {
        type: 'object',
        description: 'Present when question ranking ran without full semantic matching, or date headers could not read when facts were said.',
        properties: {
          reason: { type: 'string', description: 'Why the cosine arm did not run: keyword_only_no_embedding_provider, keyword_only_embedding_disabled, embed_timeout, embed_unavailable, no_query_terms or facts_embedding_column_missing; or fact_observed_date_unavailable: date headers show observed unknown because the source-page read failed.' },
          unembedded: { type: 'integer', description: 'Facts in scope without a comparable embedding (ranked by word overlap only).' },
        },
      },
      facts_below_floor: { type: 'integer', description: 'Present when question ranking found candidate facts and none cleared the admission floor: how many. Absent when nothing matched.' },
      facts_calibration: {
        type: 'object',
        description: 'Informational, present when question ranking used semantic matching on an embedding model whose fact admission floors were never measured: a short facts list is weaker evidence of "nothing matched". Never replaces facts_degraded.',
        required: ['status', 'model_key'],
        properties: {
          status: { type: 'string', enum: ['unmeasured'] },
          model_key: { type: 'string', description: 'provider:model@dims, the key doctor fact_admission_floors reports.' },
        },
      },
      results: {
        type: 'array',
        description: 'Search arm — present only when `query` was passed.',
        items: {
          type: 'object',
          required: ['slug', 'title', 'evidence', 'create_safety', 'provenance'],
          properties: {
            slug: { type: 'string' },
            title: { type: ['string', 'null'] },
            chunk: { type: ['string', 'null'] },
            evidence: { type: 'string', enum: EVIDENCE_ENUM },
            create_safety: { type: 'string', enum: CREATE_SAFETY_ENUM },
            provenance: { type: 'string', description: 'Origin page slug.' },
            source_id: { type: 'string', description: 'The source the hit came from (#4830; absent only when a federated read cannot name one).' },
          },
        },
      },
      search_degraded: { type: 'string', description: 'Present when the search arm fell back to keyword-only: keyword_only_no_embedding_provider (no embedding provider) or keyword_only_embedding_disabled (embeddings off by choice; no query text sent to a provider).' },
      budget_tokens: { type: 'integer', description: 'Present for a positive finite numeric budget, including when its floor is zero.' },
      budget_used: { type: 'integer' },
      dropped_count: { type: 'integer' },
      budget_packing: {
        type: 'object',
        description: 'Present only when a valid budget_policy is supplied. Per-arm used and dropped sums match budget_used and dropped_count when those fields exist.',
        required: ['policy', 'applied', 'reason', 'facts', 'results'],
        properties: {
          policy: { type: 'string', enum: ['facts_first', 'query_first'], description: 'Effective policy; ineligible query_first requests fall back to facts_first.' },
          applied: { type: 'boolean', description: 'Whether the requested budget policy applied, not whether all required evidence fit.' },
          reason: { type: 'string', enum: ['no_query', 'no_positive_finite_budget', 'budget_below_one', 'no_candidates', 'first_items_exceed_budget', 'packed'] },
          facts: RECALL_BUDGET_ARM_SCHEMA,
          results: RECALL_BUDGET_ARM_SCHEMA,
        },
      },
    },
  },
  remember: {
    type: 'object',
    required: ['id', 'status', 'status_text', 'entity_slug', 'valid_until', 'protocol_version'],
    properties: {
      protocol_version: { type: 'integer', const: MEMORY_VERBS_VERSION },
      id: { type: 'string', description: 'Opaque fact id. On status=duplicate this is the EXISTING fact\'s id.' },
      status: { type: 'string', enum: STATUS_ENUM, description: 'Branch on THIS, never on status_text.' },
      status_text: { type: 'string', description: 'Human rendering of status. Display only — never branch on it.' },
      entity_slug: { type: ['string', 'null'] },
      valid_until: { type: ['string', 'null'], description: 'ISO 8601 or null (never expires).' },
      degraded_dedup: { type: 'boolean', description: 'Present (true) when no embedding provider — near-duplicates may insert.' },
      entity_inferred: { type: 'string', enum: ['mention'], description: 'Present when `entity` was omitted and the subject was inferred from an exact mention.' },
      warnings: { type: 'array', items: { type: 'string', enum: ['NO_ENTITY', 'ENTITY_LINK_FAILED'] },
        description: 'NO_ENTITY: saved unattributed. ENTITY_LINK_FAILED: an inferred entity could not be linked; saved unattributed.' },
      hint: { type: 'string', description: 'Present with warnings: how to attribute the fact (pass `entity`).' },
      superseded_fact_id: { type: 'string', description: 'Present on status=superseded: the fact this one replaced.' },
      replaced_by_caller: { type: 'boolean', description: 'Present (true) when the caller named the replaced fact with `replaces`.' },
      write_request: WRITE_RECEIPT_SCHEMA,
    },
  },
  entity: {
    type: 'object',
    required: ['protocol_version', 'found', 'latency_ms'],
    properties: {
      protocol_version: { type: 'integer', const: MEMORY_VERBS_VERSION },
      found: { type: 'boolean' },
      latency_ms: { type: 'integer' },
      card: {
        type: 'object',
        required: ['entity', 'aka', 'summary', 'last_touched', 'open_threads', 'edges', 'backlink_count', 'active_fact_count'],
        properties: {
          entity: {
            type: 'object',
            required: ['slug', 'title', 'type'],
            properties: {
              slug: { type: 'string' }, title: { type: 'string' }, type: { type: ['string', 'null'] },
              // #6723 — ADDITIVE OPTIONAL: (source_id, slug) is the entity's identity.
              source_id: { type: 'string' },
            },
          },
          aka: { type: 'array', items: { type: 'string' } },
          summary: { type: 'string' },
          last_touched: {
            type: 'object',
            required: ['updated_at', 'last_retrieved_at', 'last_timeline_date'],
            properties: {
              updated_at: { type: ['string', 'null'] },
              last_retrieved_at: { type: ['string', 'null'] },
              last_timeline_date: { type: ['string', 'null'] },
            },
          },
          open_threads: {
            type: 'array',
            items: {
              type: 'object',
              required: ['kind', 'text', 'date'],
              properties: {
                kind: { type: 'string', enum: ['commitment', 'recent_event'] },
                text: { type: 'string' },
                date: { type: ['string', 'null'] },
                // v0.47 open-loop engine — ADDITIVE OPTIONAL (frozen-v1
                // legal); present only on threads backed by an open_loops row.
                direction: { type: 'string', enum: ['owed_by_me', 'owed_to_me', 'their_turn', 'my_turn'] },
                due: { type: ['string', 'null'] },
                counterparty: { type: ['string', 'null'] },
                status: { type: 'string' },
                loop_id: { type: 'number' },
              },
            },
          },
          edges: {
            type: 'array',
            items: {
              type: 'object',
              required: ['type', 'direction', 'slug'],
              properties: {
                type: { type: 'string' },
                direction: { type: 'string', enum: ['out', 'in'] },
                slug: { type: 'string' },
                context: { type: ['string', 'null'] },
                // Temporal typed edges — ADDITIVE OPTIONAL (frozen-v1 legal).
                status: { type: 'string' },
                since: { type: ['string', 'null'] },
                until: { type: ['string', 'null'] },
              },
            },
          },
          backlink_count: { type: 'integer' },
          active_fact_count: { type: 'integer' },
          relationship_note: { type: 'string' },
          // Entity recall — ADDITIVE OPTIONAL (frozen-v1 legal); the `entity`
          // verb sets them, ambient callers (context_pack, delta) do not.
          referenced_by_count: { type: 'integer' },
          referenced_by: {
            type: 'array',
            items: {
              type: 'object',
              required: ['canonical_type', 'total', 'rows'],
              properties: {
                canonical_type: { type: 'string' },
                total: { type: 'integer' },
                rows: { type: 'array', items: REFERENCE_ROW_SCHEMA },
                next: { type: 'object', required: ['tool', 'arguments'], properties: {
                  tool: { type: 'string', const: 'get_backlinks' }, arguments: { type: 'object' }, requires_surface: { type: 'string', enum: ['starter'] } } },
              },
            },
          },
          coverage: COVERAGE_SCHEMA,
          // F1 record view — ADDITIVE OPTIONAL (frozen-v1 legal): only when record types are enrolled.
          records: { type: 'array', items: RECORD_GROUP_SCHEMA },
          references_unavailable: REFERENCES_UNAVAILABLE_SCHEMA,
        },
      },
      coverage: COVERAGE_SCHEMA,
      suggestions: {
        type: 'array',
        items: {
          type: 'object',
          required: ['slug', 'title', 'create_safety'],
          properties: {
            slug: { type: 'string' },
            title: { type: 'string' },
            create_safety: { type: 'string', enum: CREATE_SAFETY_ENUM },
            source_id: { type: 'string' },
          },
        },
      },
    },
  },
  synthesize: {
    type: 'object',
    required: ['answer', 'sources', 'cost', 'protocol_version'],
    properties: {
      protocol_version: { type: 'integer', const: MEMORY_VERBS_VERSION },
      answer: { type: 'string', description: 'Quoted words not found in the evidence are unquoted and marked [unverified]; never present them as quotes.' },
      answer_raw: { type: 'string', description: 'With think.quote_verify on and quotes in the answer: the answer as the model wrote it.' },
      quote_check: { type: 'object', properties: { grounded: { type: 'integer' }, repaired: { type: 'integer' }, unverified: { type: 'integer' } } },
      unverified_quotes: { type: 'array', items: { type: 'object', properties: { text: { type: 'string' }, reason: { type: 'string' } } } },
      sources: { type: 'array', items: { type: 'string' } },
      gaps: { type: 'array', items: { type: 'string' } },
      cost: {
        type: 'object',
        required: ['model', 'input_tokens', 'output_tokens', 'usd_estimate'],
        description: 'Best-effort aggregate (retries/multi-call flows sum; cache hits may undercount). Honest signal, not an invoice.',
        properties: {
          model: { type: 'string' },
          input_tokens: { type: ['integer', 'null'] },
          output_tokens: { type: ['integer', 'null'] },
          usd_estimate: { type: ['number', 'null'] },
        },
      },
      // v0.45.x (WP2/T5+E2) additive compose-status fields — never required
      // (a pre-v0.45.x v1 server that omits them must still certify).
      synthesis_status: {
        type: 'string',
        enum: SYNTHESIS_STATUS_ENUM,
        description:
          'How the answer was produced. ok = LLM synthesis; extractive_fallback = compose failed with a non-empty gather — answer is an extractive digest quoting ONLY retrieved pages, sources cite the digested pages (never fabricated).',
      },
      pages_gathered: { type: 'integer', description: 'Pages retrieved by the gather phase behind this answer.' },
      takes_gathered: { type: 'integer', description: 'Takes retrieved by the gather phase behind this answer.' },
      warnings: { type: 'array', items: { type: 'string' }, description: 'Machine-stable pipeline warning codes (e.g. LLM_OUTPUT_NOT_JSON, LLM_CALL_FAILED: <class> where <class> is timeout | rate_limited | network | provider_error).' },
      // #5461 additive: the pages budget is configurable and soft; callers learn when evidence was cut and which source each cited page came from.
      evidence_truncated: { type: 'boolean', description: 'true when at least one gathered page reached the model as a cut excerpt (think.pages_budget_chars / think.excerpt_ceiling_chars, both soft bounds).' },
      citations: {
        type: 'array',
        description: 'sources[] with provenance, same order and length: the gathered source each cited slug came from (null when the model cited a slug outside the gather).',
        items: {
          type: 'object',
          required: ['slug', 'source_id'],
          properties: { slug: { type: 'string' }, source_id: { type: ['string', 'null'] }, row_num: { type: ['integer', 'null'] } },
        },
      },
    },
  },
  forget: {
    type: 'object',
    required: ['id', 'expired', 'reason', 'protocol_version'],
    properties: {
      protocol_version: { type: 'integer', const: MEMORY_VERBS_VERSION },
      id: { type: 'string' },
      expired: { type: 'boolean', description: 'true = this call expired the fact; false = it was ALREADY expired (idempotent re-forget).' },
      reason: { type: ['string', 'null'] },
      write_request: WRITE_RECEIPT_SCHEMA,
      similar_active: {
        type: 'object',
        description: 'Active facts about the same entity close in meaning to the withdrawn claim (ids and scores only; zero model calls). Similarity is not sameness: ask the user before forgetting any of them.',
        properties: {
          state: { type: 'string', enum: ['checked', 'not_checked_no_embedding', 'not_checked_pending'] },
          candidates: { type: 'array', items: { type: 'object', properties: { fact_id: { type: 'string' }, similarity: { type: 'number' } } } },
          semantic_review: { type: 'string', enum: ['scheduled', 'off', 'unavailable', 'opted_out'] },
          next: { type: 'string' },
        },
      },
    },
  },
  // v0.45.7 (issue #1) — ambient recall. World-only by default; include_private
  // widens all arms (local trusted callers only). protocol_version stays 1.
  context_pack: {
    type: 'object',
    required: ['protocol_version', 'entities', 'cards', 'open_threads', 'facts'],
    properties: {
      protocol_version: { type: 'integer', const: MEMORY_VERBS_VERSION },
      entities: { type: 'array', items: { type: 'string' } },
      cards: {
        type: 'array',
        items: {
          type: 'object',
          required: ['slug', 'title', 'summary', 'open_threads'],
          properties: {
            slug: { type: 'string' },
            // #6723 — ADDITIVE OPTIONAL: the card page's source; (source_id, slug) is the entity's identity.
            source_id: { type: 'string' },
            title: { type: 'string' },
            type: { type: ['string', 'null'] },
            summary: { type: 'string' },
            open_threads: {
              type: 'array',
              items: {
                type: 'object',
                required: ['kind', 'text', 'date'],
                properties: {
                  kind: { type: 'string', enum: ['commitment', 'recent_event'] },
                  text: { type: 'string' },
                  date: { type: ['string', 'null'] },
                  // v0.47 open-loop engine — additive optional.
                  direction: { type: 'string', enum: ['owed_by_me', 'owed_to_me', 'their_turn', 'my_turn'] },
                  due: { type: ['string', 'null'] },
                  counterparty: { type: ['string', 'null'] },
                  status: { type: 'string' },
                  loop_id: { type: 'number' },
                },
              },
            },
            edges: {
              type: 'array',
              items: {
                type: 'object',
                required: ['type', 'direction', 'slug'],
                properties: {
                  type: { type: 'string' },
                  direction: { type: 'string', enum: ['out', 'in'] },
                  slug: { type: 'string' },
                  context: { type: ['string', 'null'] },
                  status: { type: 'string' },
                  since: { type: ['string', 'null'] },
                  until: { type: ['string', 'null'] },
                },
              },
            },
            backlink_count: { type: 'integer' },
            relationship_note: { type: 'string' },
            // F3 — ADDITIVE OPTIONAL: the card page's own frontmatter `status`, only when set (entity.row_page_status).
            page_status: { type: 'string', maxLength: 40 },
            // F1 record view — ADDITIVE OPTIONAL: only when record types are enrolled (pull verb only).
            referenced_by_count: { type: 'integer' },
            records: { type: 'array', items: RECORD_GROUP_SCHEMA },
            sibling_records: { type: 'array', items: { type: 'object', required: ['slug', 'title'], properties: {
              slug: { type: 'string' }, title: { type: 'string' }, referenced_by_count: { type: 'integer' },
              records: { type: 'array', items: RECORD_GROUP_SCHEMA }, references_unavailable: REFERENCES_UNAVAILABLE_SCHEMA } } },
            references_unavailable: REFERENCES_UNAVAILABLE_SCHEMA,
          },
        },
      },
      open_threads: {
        type: 'array',
        items: {
          type: 'object',
          required: ['kind', 'text', 'date'],
          properties: {
            kind: { type: 'string', enum: ['commitment', 'recent_event'] },
            text: { type: 'string' },
            date: { type: ['string', 'null'] },
            // v0.47 open-loop engine — additive optional.
            direction: { type: 'string', enum: ['owed_by_me', 'owed_to_me', 'their_turn', 'my_turn'] },
            due: { type: ['string', 'null'] },
            counterparty: { type: ['string', 'null'] },
            status: { type: 'string' },
            loop_id: { type: 'number' },
          },
        },
      },
      facts: {
        type: 'array',
        items: {
          type: 'object',
          required: ['fact', 'kind'],
          properties: {
            fact: { type: 'string' },
            kind: { type: 'string' },
            entity_slug: { type: ['string', 'null'] },
            valid_from: { type: 'string' },
            confidence: { type: 'number' },
            fact_id: { type: 'string', description: 'Opaque protocol id — the value forget accepts.' },
            provenance: { type: ['string', 'null'], description: 'The stored source attribution (remember --provenance).' },
          },
        },
      },
      // #6724 — ADDITIVE OPTIONAL: the packed entities' own facts, keyed to their card's (source_id, slug); `facts` stays hot memory.
      entity_facts: {
        type: 'array',
        items: {
          type: 'object',
          required: ['source_id', 'slug', 'fact_id', 'fact', 'kind'],
          properties: {
            source_id: { type: 'string' },
            slug: { type: 'string', description: 'The card this fact is about.' },
            fact_id: { type: 'string', description: 'Opaque protocol id — the value forget accepts.' },
            fact: { type: 'string' },
            kind: { type: 'string' },
            entity_slug: { type: ['string', 'null'] },
            valid_from: { type: 'string' },
            context: { type: ['string', 'null'] },
            confidence: { type: 'number' },
            attributed_to: { type: ['string', 'null'] },
            provenance: { type: ['string', 'null'], description: 'The stored source attribution (remember --provenance).' },
            trust_tier: { type: 'string' },
            origin: { type: 'string' },
          },
        },
      },
      text: { type: 'string', description: 'Pre-rendered injectable block (envelope-wrapped).' },
      degraded_reason: { type: 'string', description: 'Present when a wall-clock deadline returned a partial pack.' },
      budget_tokens: { type: 'integer', description: 'Present when budget_tokens was passed.' },
      budget_used: { type: 'integer' },
      dropped_count: { type: 'integer' },
      // C4 pinned questions — additive optional, owner-capable callers only; outside `text` and the budget.
      pinned_questions: {
        type: 'array',
        description: 'Fresh sentences of pinned answers scoped to a packed entity (owner-capable callers only).',
        items: {
          type: 'object',
          required: ['id', 'question', 'answer', 'freshness'],
          properties: {
            id: { type: 'string' },
            question: { type: 'string' },
            answer: { type: 'array', items: { type: 'string' } },
            freshness: { type: 'string', enum: ['fresh', 'stale'] },
          },
        },
      },
      withheld: {
        type: 'object',
        required: ['stale_sentences', 'question_ids', 'refresh_command'],
        description: 'Pinned-answer sentences left out because their evidence changed or is unreadable.',
        properties: {
          stale_sentences: { type: 'integer' },
          question_ids: { type: 'array', items: { type: 'string' } },
          refresh_command: { type: 'string' },
        },
      },
    },
  },
  delta: {
    type: 'object',
    required: ['protocol_version', 'since', 'pages', 'facts', 'threads'],
    properties: {
      protocol_version: { type: 'integer', const: MEMORY_VERBS_VERSION },
      since: { type: 'string', description: 'The ISO cursor this delta was computed against.' },
      has_more: { type: 'boolean', description: 'True when more content is waiting (a fetch limit or the budget); each arm advanced only through what it delivered, so the rest surfaces on the next wake. Failure is degraded_reason, never has_more.' },
      next_cursor: {
        type: 'object',
        required: ['since', 'slug'],
        description: 'Where to resume. `cursor` (opaque, both arms exact) is passed back as cursor; older clients pass since + since_slug, which is conservative (may re-deliver, never skips): it holds while any arm failed and stays strictly before the oldest undelivered fact.',
        properties: { since: { type: 'string' }, slug: { type: 'string' }, cursor: { type: 'string' } },
      },
      cursor_arms: {
        type: 'object',
        description: 'Replay audit trail: each arm\'s start and next keyset (pages: since + slug; facts: since + id).',
      },
      pages: {
        type: 'array',
        items: {
          type: 'object',
          required: ['slug', 'title', 'updated_at'],
          properties: {
            slug: { type: 'string' },
            source_id: { type: 'string' },
            title: { type: 'string' },
            updated_at: { type: 'string' },
          },
        },
      },
      facts: {
        type: 'array',
        items: {
          type: 'object',
          required: ['fact', 'kind'],
          properties: {
            id: { type: 'integer', description: 'Fact id (dedupe key for replay).' },
            fact: { type: 'string' },
            kind: { type: 'string' },
            entity_slug: { type: ['string', 'null'] },
            valid_from: { type: 'string' },
            confidence: { type: 'number' },
            fact_id: { type: 'string', description: 'Opaque protocol id — the value forget accepts.' },
            provenance: { type: ['string', 'null'], description: 'The stored source attribution (remember --provenance).' },
          },
        },
      },
      threads: {
        type: 'array',
        items: {
          type: 'object',
          required: ['kind', 'text', 'date'],
          properties: {
            kind: { type: 'string', enum: ['commitment', 'recent_event'] },
            text: { type: 'string' },
            date: { type: ['string', 'null'] },
          },
        },
      },
      text: { type: 'string' },
      degraded_reason: { type: 'string', description: 'Comma-joined incomplete parts: deadline, pages, facts, threads, session_state. No cursor moved past anything undelivered; a delta_incomplete notice carries the retry step.' },
      budget_tokens: { type: 'integer' },
      budget_used: { type: 'integer' },
      dropped_count: { type: 'integer' },
    },
  },
};

/** Error envelope schema (uniform across all verbs). */
export const ERROR_SCHEMA: Record<string, unknown> = {
  type: 'object',
  required: ['error', 'message'],
  properties: {
    error: {
      type: 'string',
      enum: [
        'invalid_params',
        'provenance_required',
        'not_found',
        'scope_denied',
        'unavailable',
        'budget_unsatisfiable', // RESERVED — schema-listed, never returned in v1
        'internal',
      ],
    },
    message: { type: 'string' },
    suggestion: { type: 'string', description: 'Populated on every verb error: problem + cause + fix.' },
    detail: { type: 'string', description: 'Freeform specifics (e.g. which dependency failed).' },
    protocol_version: { type: 'integer', const: MEMORY_VERBS_VERSION },
    write_request: WRITE_RECEIPT_SCHEMA,
    write_error: { type: 'string', enum: [...WRITE_ERROR_CODES] },
    withdrawn: {
      type: 'object',
      required: ['at', 'subject', 'visibility'],
      description: 'Additive, on a fact_withdrawn refusal: when and for which subject (an entity slug, or all_entities) the exact claim was forgotten. Absence carries no meaning.',
      properties: {
        at: { type: 'string' },
        subject: { type: 'string' },
        visibility: { type: 'string', enum: ['world', 'private'] },
      },
    },
  },
};