Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Write attribution (Foundations 1, F1): which journal request and principal
* wrote each content row and each live page revision. One canonical copy used
* by the f1_write_attribution schema migration. Like the facts/takes DDL it
* is not in the schema blob: a fresh install replays every migration, so the
* columns land after every migration-added column on fresh and upgraded
* brains alike, and no trigger can run before the columns it names exist.
*
* The actor reaches the database as three transaction-local settings that
* withCoordinatedWrite / withWriteAttribution set (persistence/context.ts):
* gbrain.write_request (persistence_requests.id, empty for maintenance),
* gbrain.write_principal_kind and gbrain.write_principal_id. BEFORE ROW
* triggers copy them into the rows, so no INSERT/UPDATE site carries
* attribution itself. Every column is nullable with no default (metadata-only
* ADD COLUMN on both engines, #5216). All-NULL reads as "unrecorded".
*
* A column added to facts, takes or timeline_entries must be classified here
* (content or projection) and the trigger function re-created by that
* migration (re-run WRITE_ATTRIBUTION_SCHEMA_SQL, as v192 re-runs the writer
* guard); the classification test in test/write-attribution.test.ts fails
* until it is.
*/
import { TRUST_ROW_COLUMNS } from '../trust/schema.ts';
import { requireMaintainerPoliciesSql } from '../derived-state-maintainers.ts';
/** created_by and last_mutated_by on facts, takes and timeline_entries. */
export const ROW_ATTRIBUTION_COLUMNS = [
'write_request_id', 'write_principal_kind', 'write_principal_id',
'last_write_request_id', 'last_write_principal_kind', 'last_write_principal_id', 'last_written_at',
] as const;
/** The actor that wrote the live page revision (pages.knowledge_revision). */
export const REVISION_ATTRIBUTION_COLUMNS = ['revision_write_request_id', 'revision_principal_kind', 'revision_principal_id'] as const;
/** page_versions: origin of the snapshotted revision, and the write that archived it. */
export const VERSION_ATTRIBUTION_COLUMNS = [
'write_request_id', 'write_principal_kind', 'write_principal_id',
'archived_write_request_id', 'archived_principal_kind', 'archived_principal_id',
] as const;
export type AttributedTable = 'facts' | 'takes' | 'timeline_entries';
/** A change to any of these is a canonical mutation and moves last_write_*. */
export const WRITE_ATTRIBUTION_CONTENT_COLUMNS: Record<AttributedTable, readonly string[]> = {
facts: ['id', 'source_id', 'entity_slug', 'fact', 'kind', 'visibility', 'notability', 'context', 'valid_from',
'valid_until', 'expired_at', 'superseded_by', 'consolidated_at', 'consolidated_into', 'source', 'source_session',
'confidence', 'created_at', 'row_num', 'source_markdown_slug', 'claim_metric', 'claim_value', 'claim_unit',
'claim_period', 'event_type', 'dimension', 'value', 'value_hash', 'dim_status', 'attributed_to'],
takes: ['id', 'page_id', 'row_num', 'claim', 'kind', 'holder', 'weight', 'since_date', 'until_date', 'source',
'superseded_by', 'active', 'resolved_at', 'resolved_outcome', 'resolved_value', 'resolved_unit', 'resolved_source',
'resolved_by', 'created_at', 'resolved_quality'],
timeline_entries: ['id', 'page_id', 'date', 'source', 'summary', 'detail', 'event_page_id', 'created_at'],
};
/**
* Columns whose change leaves attribution untouched: physical projections
* (embeddings and their identity) and the trust tier and its origin record,
* which trust/schema.ts stamps and guards (a confirmation or backfill is not a
* content rewrite, so it does not move last_write_*).
*/
export const WRITE_ATTRIBUTION_PROJECTION_COLUMNS: Record<AttributedTable, readonly string[]> = {
facts: ['embedding', 'embedded_at', 'embedding_model', 'embedded_text_hash', 'source_window', ...TRUST_ROW_COLUMNS],
takes: ['embedding', 'embedded_at', 'updated_at', 'embedding_model', 'embedded_text_hash', ...TRUST_ROW_COLUMNS],
timeline_entries: [...TRUST_ROW_COLUMNS],
};
const ATTRIBUTED_TABLES = Object.keys(WRITE_ATTRIBUTION_CONTENT_COLUMNS) as AttributedTable[];
const SETTINGS = `
req := NULLIF(current_setting('gbrain.write_request', true), '')::uuid;
principal_kind := NULLIF(current_setting('gbrain.write_principal_kind', true), '');
principal_id := NULLIF(current_setting('gbrain.write_principal_id', true), '');`;
const tuple = (row: 'NEW' | 'OLD', columns: readonly string[]) => `(${columns.map(column => `${row}.${column}`).join(', ')})`;
const contentChanged = (table: AttributedTable) => {
const columns = WRITE_ATTRIBUTION_CONTENT_COLUMNS[table];
return `${tuple('NEW', columns)} IS DISTINCT FROM ${tuple('OLD', columns)}`;
};
const typed = (column: string) => column.endsWith('request_id') ? 'UUID' : column.endsWith('_at') ? 'TIMESTAMPTZ' : 'TEXT';
const addColumns = (table: string, columns: readonly string[]) =>
`ALTER TABLE ${table} ${columns.map(column => `ADD COLUMN IF NOT EXISTS ${column} ${typed(column)}`).join(', ')}`;
/**
* Set transaction-locally by the facts insert guard (facts/insert-guard-schema.ts)
* around its withdrawal stamp, which runs as an UPDATE at the end of the
* inserting statement; the per-row guard it replaced stamped the row before
* insert, where attribution never saw a change.
*/
export const FACT_WITHDRAWAL_STAMP_SETTING = 'gbrain.fact_withdrawal_stamp';
const FACT_CONTENT_WITHOUT_STAMP = WRITE_ATTRIBUTION_CONTENT_COLUMNS.facts.filter(column => column !== 'expired_at' && column !== 'valid_until');
/**
* INSERT: stamp created_by and last_mutated_by from the settings; without
* settings keep supplied values (engine copy, backfill). UPDATE: created_by is
* immutable once set; last_mutated_by moves only when a content column
* changed (to NULL when no actor is set: an unattributed writer mutated it).
* Either pair may be filled while it is still NULL (journal backfill).
* Under FACT_WITHDRAWAL_STAMP_SETTING a facts UPDATE that changes only
* expired_at and valid_until is not a content change, so last_mutated_by
* keeps the inserted (or supplied) values; any other content change still
* moves it.
*/
export const STAMP_ROW_FUNCTION = `CREATE OR REPLACE FUNCTION gbrain_stamp_write_attribution() RETURNS trigger LANGUAGE plpgsql SET search_path = pg_catalog, public, pg_temp AS $fn$
DECLARE req uuid; principal_kind text; principal_id text; changed boolean;
BEGIN${SETTINGS}
IF TG_OP = 'INSERT' THEN
IF principal_kind IS NOT NULL THEN
NEW.write_request_id := req; NEW.write_principal_kind := principal_kind; NEW.write_principal_id := principal_id;
NEW.last_write_request_id := req; NEW.last_write_principal_kind := principal_kind; NEW.last_write_principal_id := principal_id;
NEW.last_written_at := now();
END IF;
RETURN NEW;
END IF;
IF (OLD.write_request_id, OLD.write_principal_kind, OLD.write_principal_id) IS DISTINCT FROM (NULL::uuid, NULL::text, NULL::text) THEN
NEW.write_request_id := OLD.write_request_id; NEW.write_principal_kind := OLD.write_principal_kind; NEW.write_principal_id := OLD.write_principal_id;
END IF;
${ATTRIBUTED_TABLES.map((table, index) => `${index === 0 ? 'IF' : 'ELSIF'} TG_TABLE_NAME = '${table}' THEN
changed := ${contentChanged(table)};`).join('\n ')}
ELSE
RAISE EXCEPTION 'gbrain_stamp_write_attribution is not classified for table %', TG_TABLE_NAME;
END IF;
IF changed AND TG_TABLE_NAME = 'facts' AND COALESCE(current_setting('${FACT_WITHDRAWAL_STAMP_SETTING}', true), '') = 'on' THEN
changed := ${tuple('NEW', FACT_CONTENT_WITHOUT_STAMP)} IS DISTINCT FROM ${tuple('OLD', FACT_CONTENT_WITHOUT_STAMP)};
END IF;
IF changed THEN
NEW.last_write_request_id := req; NEW.last_write_principal_kind := principal_kind; NEW.last_write_principal_id := principal_id;
NEW.last_written_at := now();
ELSIF (OLD.last_write_request_id, OLD.last_write_principal_kind, OLD.last_write_principal_id, OLD.last_written_at)
IS DISTINCT FROM (NULL::uuid, NULL::text, NULL::text, NULL::timestamptz) THEN
NEW.last_write_request_id := OLD.last_write_request_id; NEW.last_write_principal_kind := OLD.last_write_principal_kind;
NEW.last_write_principal_id := OLD.last_write_principal_id; NEW.last_written_at := OLD.last_written_at;
END IF;
RETURN NEW;
END $fn$`;
/**
* Sorts after pages_knowledge_revision, which assigns the new revision. Tag
* writes bump the revision through an update of the page row, so they are
* attributed too.
*/
const STAMP_REVISION_FUNCTION = `CREATE OR REPLACE FUNCTION gbrain_stamp_revision_attribution() RETURNS trigger LANGUAGE plpgsql SET search_path = pg_catalog, public, pg_temp AS $fn$
DECLARE req uuid; principal_kind text; principal_id text;
BEGIN${SETTINGS}
IF TG_OP = 'INSERT' THEN
IF principal_kind IS NOT NULL THEN
NEW.revision_write_request_id := req; NEW.revision_principal_kind := principal_kind; NEW.revision_principal_id := principal_id;
END IF;
ELSIF NEW.knowledge_revision IS DISTINCT FROM OLD.knowledge_revision THEN
NEW.revision_write_request_id := req; NEW.revision_principal_kind := principal_kind; NEW.revision_principal_id := principal_id;
ELSIF (OLD.revision_write_request_id, OLD.revision_principal_kind, OLD.revision_principal_id) IS DISTINCT FROM (NULL::uuid, NULL::text, NULL::text) THEN
NEW.revision_write_request_id := OLD.revision_write_request_id; NEW.revision_principal_kind := OLD.revision_principal_kind;
NEW.revision_principal_id := OLD.revision_principal_id;
END IF;
RETURN NEW;
END $fn$`;
/**
* A version row snapshots the page before the archiving write changes it, in
* the same transaction, so the page row still carries the snapshotted
* revision and its writer. The archiving actor comes from the settings.
* Under RLS the archiving writer needs the page (#7637, derived-state-maintainers.ts).
*/
export const STAMP_VERSION_FUNCTION = `CREATE OR REPLACE FUNCTION gbrain_stamp_version_attribution() RETURNS trigger LANGUAGE plpgsql SET search_path = pg_catalog, public, pg_temp AS $fn$
DECLARE req uuid; principal_kind text; principal_id text;
BEGIN${SETTINGS}
IF (NEW.write_request_id, NEW.write_principal_kind, NEW.write_principal_id) IS NOT DISTINCT FROM (NULL::uuid, NULL::text, NULL::text) THEN
${requireMaintainerPoliciesSql('pages', ['SELECT'], ' ')}
SELECT p.revision_write_request_id, p.revision_principal_kind, p.revision_principal_id
INTO NEW.write_request_id, NEW.write_principal_kind, NEW.write_principal_id
FROM pages p WHERE p.id = NEW.page_id AND p.knowledge_revision = NEW.knowledge_revision;
END IF;
IF principal_kind IS NOT NULL THEN
NEW.archived_write_request_id := req; NEW.archived_principal_kind := principal_kind; NEW.archived_principal_id := principal_id;
END IF;
RETURN NEW;
END $fn$`;
export const WRITE_ATTRIBUTION_SCHEMA_STATEMENTS = [
addColumns('pages', REVISION_ATTRIBUTION_COLUMNS),
addColumns('page_versions', VERSION_ATTRIBUTION_COLUMNS),
...ATTRIBUTED_TABLES.map(table => addColumns(table, ROW_ATTRIBUTION_COLUMNS)),
STAMP_ROW_FUNCTION,
STAMP_REVISION_FUNCTION,
STAMP_VERSION_FUNCTION,
...ATTRIBUTED_TABLES.flatMap(table => [
`DROP TRIGGER IF EXISTS gbrain_write_attribution ON ${table}`,
`CREATE TRIGGER gbrain_write_attribution BEFORE INSERT OR UPDATE ON ${table} FOR EACH ROW EXECUTE FUNCTION gbrain_stamp_write_attribution()`,
]),
`DROP TRIGGER IF EXISTS pages_revision_attribution ON pages`,
`CREATE TRIGGER pages_revision_attribution BEFORE INSERT OR UPDATE ON pages FOR EACH ROW EXECUTE FUNCTION gbrain_stamp_revision_attribution()`,
`DROP TRIGGER IF EXISTS page_versions_write_attribution ON page_versions`,
`CREATE TRIGGER page_versions_write_attribution BEFORE INSERT ON page_versions FOR EACH ROW EXECUTE FUNCTION gbrain_stamp_version_attribution()`,
] as const;
export const WRITE_ATTRIBUTION_SCHEMA_SQL = `${WRITE_ATTRIBUTION_SCHEMA_STATEMENTS.join(';\n')};\n`;