Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Source-string constants for the durable audit checkpoint rows that
* extract-conversation-facts writes into the facts table to mark
* batch-run progress:
* - `TERMINAL_AUDIT_SOURCE` — page-level "extraction complete" checkpoint
* (Eng-v2 C7). Doctor's backlog query matches this source +
* source_session, not the per-segment fact source.
* - `NON_EXTRACTABLE_AUDIT_SOURCE` — durable outcome for a successfully
* scanned page that contains no eligible multi-message segment, kept
* distinct from successful extraction so operator surfaces can report
* the truth without rescanning the page forever.
* - `LEGACY_TERMINAL_AUDIT_SOURCE` — the pre-`:v2` spelling of
* TERMINAL_AUDIT_SOURCE. `src/core/migrate.ts`'s doctor-backlog-index
* comment and `test/extract-conversation-facts.test.ts` ("legacy
* terminal rows do not suppress strict v2 replay") both reference this
* exact string, so brains upgraded through the pre-v2 checkpoint scheme
* can still carry rows under it. Excluded from recall the same as the
* current spelling — a legacy checkpoint is not a user fact either.
*
* These are checkpoints, not user facts. Recall-side callers filter rows
* whose `source` is one of these out of the newest-N fetch window (see
* `FactListOpts.excludeAuditRows` in `../engine.ts`).
*
* Pulled into a leaf module (no other imports) so `pglite-engine.ts` and
* `postgres-engine.ts` — engine-live paths where runtime dynamic `import()`
* is forbidden (`scripts/check-engine-dynamic-import.sh`) — can reference
* these values via a static top-level import instead of reaching into the
* much heavier `commands/extract-conversation-facts.ts` command module.
* `extract-conversation-facts.ts` re-exports both current names unchanged
* so its existing importers are unaffected.
*/
/** The `facts.source` prefix of every row the conversation-facts extractor writes (its facts and its audit rows). */
export const CONVERSATION_FACTS_SOURCE_PREFIX = 'cli:extract-conversation-facts';
export const TERMINAL_AUDIT_SOURCE = 'cli:extract-conversation-facts:terminal:v2';
export const NON_EXTRACTABLE_AUDIT_SOURCE =
'cli:extract-conversation-facts:non-extractable:v2';
export const LEGACY_TERMINAL_AUDIT_SOURCE = 'cli:extract-conversation-facts:terminal';
/** All audit-row source values (current + legacy), for callers that want a single IN-list. */
export const AUDIT_ROW_SOURCES = [
TERMINAL_AUDIT_SOURCE,
NON_EXTRACTABLE_AUDIT_SOURCE,
LEGACY_TERMINAL_AUDIT_SOURCE,
] as const;
/** The fixed claim text of each outcome row (`terminalAuditFact`, `nonExtractableAuditFact`). */
export const OUTCOME_MARKER_FACTS = ['EXTRACTION_COMPLETE', 'EXTRACTION_NOT_APPLICABLE'] as const;
/**
* #7778: true for an extraction outcome row, the bookkeeping marker every
* conversation page carries with the same text. It is not a user claim, so no
* purge tombstone applies to it and no purge or forget writes one: a
* subject-'*' tombstone on its fingerprint would keep every page of the
* source from ever completing. Both the source and the exact marker text must
* match, so a user claim keeps every purge guarantee whatever its source.
*/
export function isOutcomeMarker(row: { source?: string | null; fact: string }): boolean {
return (AUDIT_ROW_SOURCES as readonly string[]).includes(row.source ?? '') && (OUTCOME_MARKER_FACTS as readonly string[]).includes(row.fact);
}
/** SQL twin of `isOutcomeMarker` over a facts row alias (constants only, no parameters). */
export function outcomeMarkerSql(alias: string): string {
const list = (values: readonly string[]) => values.map(v => `'${v}'`).join(',');
return `(${alias}.source IN (${list(AUDIT_ROW_SOURCES)}) AND ${alias}.fact IN (${list(OUTCOME_MARKER_FACTS)}))`;
}
/**
* Decision 8 (wave 9 follow-ups): the conversation parser + extractor
* semantic version. Bump it when a parser or extractor change alters what an
* already-scanned page yields. New outcome rows carry it in their `context`
* (`extractor_version=<n>`) and a managed publication carries it in its
* generation identity. An outcome recorded under an older version stays
* fresh: nothing reopens automatically; doctor counts it as stale.
*/
export const CONVERSATION_EXTRACTOR_VERSION = 1;
const EXTRACTOR_VERSION_RE = /(?:^|; )extractor_version=(\d+)$/;
/** The outcome row context with the current extractor version stamped on it. */
export function stampExtractorVersion(context: string | null | undefined): string {
const stamp = `extractor_version=${CONVERSATION_EXTRACTOR_VERSION}`;
return context ? `${context}; ${stamp}` : stamp;
}
/** The extractor version an outcome row was recorded under, or null for a row older than the stamp. */
export function outcomeExtractorVersion(context: string | null | undefined): number | null {
const match = context ? EXTRACTOR_VERSION_RE.exec(context) : null;
return match ? Number(match[1]) : null;
}