Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
16.2 KB
Raw Blame
import { MANAGED_WRITER_GUARD_SQL } from './writer-guard-schema.ts';
/** Permanent terminal receipts stay outside owner recovery scans after cleanup. */
export const PERSISTENCE_REQUEST_RECOVERY_INDEX_SQL = `CREATE INDEX IF NOT EXISTS persistence_requests_recovery
  ON persistence_requests(worktree_id,sequence) WHERE recovery IS NOT NULL`;
export const PERSISTENCE_DATABASE_PENDING_INDEX_SQL = `CREATE INDEX IF NOT EXISTS persistence_requests_database_pending
  ON persistence_requests(source_incarnation,sequence) WHERE worktree_id IS NULL AND state IN ('queued','running','recovering')`;
/**
 * #5762: the managed sync checkpoint validation probes (sync-prepare.ts) read a
 * run's open page receipts and its committed siblings through these. Postgres
 * builds them CONCURRENTLY in a schema migration (never inside the blob);
 * PGLite and a brand-new request table (v151) build them inline.
 */
export const PERSISTENCE_SYNC_RUN_OPEN_INDEX_SQL = `CREATE INDEX IF NOT EXISTS persistence_requests_sync_run_open
  ON persistence_requests(worktree_id,(intent->>'runId')) WHERE state<>'committed' AND intent->>'kind' IN ('managed_sync_import','managed_sync_delete')`;
export const PERSISTENCE_SYNC_RUN_COMMITTED_INDEX_SQL = `CREATE INDEX IF NOT EXISTS persistence_requests_sync_run_committed
  ON persistence_requests(source_id,(intent->>'runId'),(intent->>'index')) WHERE state='committed' AND intent ? 'runId'`;
export const PERSISTENCE_SYNC_RUN_INDEXES = [
  { name: 'persistence_requests_sync_run_open', sql: PERSISTENCE_SYNC_RUN_OPEN_INDEX_SQL },
  { name: 'persistence_requests_sync_run_committed', sql: PERSISTENCE_SYNC_RUN_COMMITTED_INDEX_SQL },
] as const;
/**
 * #6511: the page purge's lookup of stored intents for a slug (`findRequestsForSlugs`: source, slug, uncompacted rows
 * with an intent) ran as a sequential scan of the request table inside the 5 s purge transaction. Postgres builds it
 * CONCURRENTLY in the persistence_request_slug_intent_index migration (`transaction: false`); PGLite inline. `gbrain repair request-indexes` rebuilds it.
 */
export const PERSISTENCE_REQUEST_SLUG_INTENT_INDEX_SQL = `CREATE INDEX IF NOT EXISTS persistence_requests_slug_intent
  ON persistence_requests(source_id,slug,sequence) WHERE intent IS NOT NULL AND NOT compacted`;
export const PERSISTENCE_REQUEST_SLUG_INTENT_INDEX = { name: 'persistence_requests_slug_intent', table: 'persistence_requests', sql: PERSISTENCE_REQUEST_SLUG_INTENT_INDEX_SQL } as const;
/**
 * #6757: dream synthesis postprocessing joins each child's committed `put_page` to its journal row by request id
 * within the cycle's source (`loadCommittedSynthesisOutputs`). The only index holding `request_id` leads with the
 * principal, which that read does not know, so it ran as a sequential scan of the request table. Postgres builds it
 * CONCURRENTLY in the persistence_request_id_index migration (`transaction: false`); PGLite inline.
 */
export const PERSISTENCE_REQUEST_ID_INDEX_SQL = `CREATE INDEX IF NOT EXISTS persistence_requests_request_id
  ON persistence_requests(source_id,request_id)`;
export const PERSISTENCE_REQUEST_ID_INDEX = { name: 'persistence_requests_request_id', table: 'persistence_requests', sql: PERSISTENCE_REQUEST_ID_INDEX_SQL } as const;
/**
 * #7649: the write claims' foreground-commit probe (journal.ts `FOREGROUND_WAITING_ON`: a committed non-sync request on the
 * worktree after the `syncSeen` bound). After a restart the bound is 0, and with no index on (worktree, sequence) for committed
 * rows the probe walked the sequence key (or the heap) through every receipt, sync receipts included, on each claim. The
 * predicate is the probe's `state='committed' AND NOT SYNC_KIND(c)` written the same way, so the planner can use it; like the probe it
 * also covers compacted receipts of any kind (their intent is NULL), so on a long-lived brain it holds most committed rows. Postgres
 * builds it CONCURRENTLY in the persistence_foreground_committed_index migration (`transaction: false`); PGLite inline.
 */
export const PERSISTENCE_FOREGROUND_COMMITTED_INDEX_SQL = `CREATE INDEX IF NOT EXISTS persistence_requests_foreground_committed
  ON persistence_requests(worktree_id,sequence) WHERE state='committed' AND NOT COALESCE(intent->>'kind','') LIKE 'managed_sync_%'`;
export const PERSISTENCE_FOREGROUND_COMMITTED_INDEX = { name: 'persistence_requests_foreground_committed', table: 'persistence_requests', sql: PERSISTENCE_FOREGROUND_COMMITTED_INDEX_SQL } as const;
/**
 * #8707: `gbrain repair failed-writes` finds a refused write's replay attempts by request id alone (the id is derived
 * from the refused request, so neither the principal nor the source is known), and finds the later requests of its page
 * (supersession, recovered fact requests) by source, slug and sequence over every receipt, compacted ones included,
 * which the partial slug index above does not hold. Without these each lookup was a sequential scan of the request
 * table, and the preview ran several per refused write. Postgres builds them CONCURRENTLY in the
 * persistence_request_replay_indexes migration (`transaction: false`); PGLite inline.
 */
export const PERSISTENCE_REQUEST_REPLAY_ID_INDEX_SQL = `CREATE INDEX IF NOT EXISTS persistence_requests_replay_id
  ON persistence_requests(request_id)`;
export const PERSISTENCE_REQUEST_REPLAY_ID_INDEX = { name: 'persistence_requests_replay_id', table: 'persistence_requests', sql: PERSISTENCE_REQUEST_REPLAY_ID_INDEX_SQL } as const;
export const PERSISTENCE_REQUEST_SLUG_SEQUENCE_INDEX_SQL = `CREATE INDEX IF NOT EXISTS persistence_requests_slug_sequence
  ON persistence_requests(source_id,slug,sequence)`;
export const PERSISTENCE_REQUEST_SLUG_SEQUENCE_INDEX = { name: 'persistence_requests_slug_sequence', table: 'persistence_requests', sql: PERSISTENCE_REQUEST_SLUG_SEQUENCE_INDEX_SQL } as const;
/** Every request-table index built online (a migration, then `gbrain repair request-indexes` and doctor `persistence_request_indexes`). */
export const PERSISTENCE_REQUEST_ONLINE_INDEXES = [...PERSISTENCE_SYNC_RUN_INDEXES, PERSISTENCE_REQUEST_SLUG_INTENT_INDEX, PERSISTENCE_REQUEST_ID_INDEX,
  PERSISTENCE_FOREGROUND_COMMITTED_INDEX, PERSISTENCE_REQUEST_REPLAY_ID_INDEX, PERSISTENCE_REQUEST_SLUG_SEQUENCE_INDEX] as const;
/**
 * #6317: the movement watermark (the newest committed receipt of a worktree)
 * that `writer movement`, `data_moving` and doctor `managed_sync_not_moving`
 * read; the baseline indexes cover pending, recovery and principal reads
 * only. Postgres builds it CONCURRENTLY in migration v222; PGLite inline.
 * Superseded by the sync watermark below: v223 drops it, and fresh installs
 * build only the new one.
 */
export const PERSISTENCE_COMMITTED_WATERMARK_INDEX_SQL = `CREATE INDEX IF NOT EXISTS persistence_requests_committed_watermark
  ON persistence_requests(worktree_id,completed_at DESC) WHERE state='committed'`;
export const PERSISTENCE_COMMITTED_WATERMARK_INDEX = { name: 'persistence_requests_committed_watermark', table: 'persistence_requests', sql: PERSISTENCE_COMMITTED_WATERMARK_INDEX_SQL } as const;
/**
 * The movement watermark read (sync-movement.ts): the newest committed managed
 * sync receipt of one worktree and incarnation. v222's index above holds every
 * committed receipt, so on a brain whose newest receipts are imports or
 * maintenance writes the read walked all of them and detoasted each intent to
 * test its kind (about 1 s at 50k receipts). Receipts are permanent (compaction
 * after `persistence.receipt_retention_days` only drops the intent), so that
 * walk grew with every write. This index holds only the receipts the read can
 * return, and compaction removes a receipt from it. Postgres builds it
 * CONCURRENTLY in migration v223, which drops v222's index; PGLite inline.
 */
export const PERSISTENCE_SYNC_WATERMARK_INDEX_SQL = `CREATE INDEX IF NOT EXISTS persistence_requests_sync_watermark
  ON persistence_requests(worktree_id,source_incarnation,completed_at DESC) WHERE state='committed' AND COALESCE(intent->>'kind','') LIKE 'managed_sync_%'`;
export const PERSISTENCE_SYNC_WATERMARK_INDEX = { name: 'persistence_requests_sync_watermark', table: 'persistence_requests', sql: PERSISTENCE_SYNC_WATERMARK_INDEX_SQL } as const;
/**
 * Receipt compaction's candidate scan (journal.ts `compactWriteReceipts`, on
 * every idle maintenance tick of a resident consumer): terminal receipts not
 * yet compacted whose `completed_at` is past the retention window. Without it
 * the scan read every receipt ever written (82 ms at 50k receipts, growing with
 * each write) to find none. Compaction removes a receipt from the index.
 * Postgres builds it CONCURRENTLY in migration v223; PGLite inline.
 */
export const PERSISTENCE_COMPACTABLE_INDEX_SQL = `CREATE INDEX IF NOT EXISTS persistence_requests_compactable
  ON persistence_requests(completed_at) WHERE recovery IS NULL AND NOT compacted AND state IN ('committed','conflict','failed','cancelled')`;
export const PERSISTENCE_COMPACTABLE_INDEX = { name: 'persistence_requests_compactable', table: 'persistence_requests', sql: PERSISTENCE_COMPACTABLE_INDEX_SQL } as const;
/**
 * #6317: one row per process that runs a full persistence consumer on a host
 * (consumer-heartbeat.ts). The primary key carries the process nonce, so a
 * reused pid after a container restart is a new row; `pid_ns` tells pid
 * namespaces apart. `renewed_at` is the liveness signal (live within 30 s,
 * lapsed at 60 s, purged by a renewal after 90 s); `restart_required` and
 * `root_barrier_age_ms` are the owner's own wedge report; `host_json_path`,
 * `persistence_home` and `minted_under` let doctor name the owner's identity
 * file without reading its filesystem.
 */
export const PERSISTENCE_CONSUMERS_TABLE_SQL = `CREATE TABLE IF NOT EXISTS persistence_consumers (
    host_id uuid NOT NULL,
    pid integer NOT NULL,
    nonce text NOT NULL,
    pid_ns text,
    kind text NOT NULL,
    mode text NOT NULL CHECK (mode IN ('probing','full','waiter_only','promoted')),
    started_at timestamptz NOT NULL DEFAULT now(),
    renewed_at timestamptz NOT NULL DEFAULT now(),
    restart_required boolean NOT NULL DEFAULT false,
    root_barrier_age_ms integer,
    pool jsonb,
    host_json_path text NOT NULL,
    persistence_home text NOT NULL,
    minted_under jsonb,
    version text NOT NULL,
    boot_id text,
    process_start text,
    segment_reader boolean,
    PRIMARY KEY(host_id,pid,nonce)
  )`;
/** Indexes the Postgres blob omits because a migration builds them CONCURRENTLY. */
export const POSTGRES_CONCURRENT_PERSISTENCE_INDEXES: ReadonlySet<string> = new Set([
  PERSISTENCE_DATABASE_PENDING_INDEX_SQL, PERSISTENCE_SYNC_RUN_OPEN_INDEX_SQL, PERSISTENCE_SYNC_RUN_COMMITTED_INDEX_SQL, PERSISTENCE_SYNC_WATERMARK_INDEX_SQL, PERSISTENCE_COMPACTABLE_INDEX_SQL,
  PERSISTENCE_REQUEST_SLUG_INTENT_INDEX_SQL, PERSISTENCE_REQUEST_ID_INDEX_SQL, PERSISTENCE_FOREGROUND_COMMITTED_INDEX_SQL,
  PERSISTENCE_REQUEST_REPLAY_ID_INDEX_SQL, PERSISTENCE_REQUEST_SLUG_SEQUENCE_INDEX_SQL,
]);
/** Durable infrastructure: never reconstruct or discard these rows during page reindexing. */
export const PERSISTENCE_SCHEMA_STATEMENTS = [
  `CREATE TABLE IF NOT EXISTS persistence_brain (
    singleton integer PRIMARY KEY CHECK (singleton = 1),
    brain_id uuid NOT NULL DEFAULT gen_random_uuid(),
    enabled boolean NOT NULL DEFAULT false,
    activated_at timestamptz
  )`,
  `INSERT INTO persistence_brain(singleton) VALUES (1) ON CONFLICT DO NOTHING`,
  `CREATE TABLE IF NOT EXISTS persistence_worktrees (
    id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
    owner_host_id uuid,
    owner_epoch bigint NOT NULL DEFAULT 0,
    topology_generation bigint NOT NULL DEFAULT 1,
    state text NOT NULL DEFAULT 'active' CHECK (state IN ('active','draining','recovering')),
    manifest jsonb,
    heartbeat_at timestamptz,
    created_at timestamptz NOT NULL DEFAULT now()
  )`,
  `CREATE TABLE IF NOT EXISTS persistence_source_bindings (
    source_id text PRIMARY KEY,
    source_incarnation uuid NOT NULL,
    worktree_id uuid NOT NULL REFERENCES persistence_worktrees(id),
    relative_path text NOT NULL DEFAULT '',
    topology_generation bigint NOT NULL DEFAULT 1
  )`,
  `CREATE TABLE IF NOT EXISTS persistence_host_bindings (
    worktree_id uuid NOT NULL REFERENCES persistence_worktrees(id),
    host_id uuid NOT NULL,
    local_path text NOT NULL,
    coordination_path text NOT NULL,
    git_durability text CHECK (git_durability IN ('enabled','disabled')),
    PRIMARY KEY(worktree_id,host_id)
  )`,
  `CREATE TABLE IF NOT EXISTS persistence_local_writers (
    id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
    lane text NOT NULL CHECK (lane IN ('cli','stdio')),
    credential_hash text NOT NULL UNIQUE,
    grant_ceiling jsonb NOT NULL,
    revoked_at timestamptz,
    created_at timestamptz NOT NULL DEFAULT now()
  )`,
  `CREATE TABLE IF NOT EXISTS persistence_counters (
    key text PRIMARY KEY,
    outstanding_count bigint NOT NULL DEFAULT 0 CHECK (outstanding_count >= 0),
    intent_bytes bigint NOT NULL DEFAULT 0 CHECK (intent_bytes >= 0),
    lifetime_ids bigint NOT NULL DEFAULT 0 CHECK (lifetime_ids >= 0),
    terminal_bytes bigint NOT NULL DEFAULT 0 CHECK (terminal_bytes >= 0),
    recovery_bytes bigint NOT NULL DEFAULT 0 CHECK (recovery_bytes >= 0)
  )`,
  `CREATE TABLE IF NOT EXISTS persistence_requests (
    id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
    principal_kind text NOT NULL CHECK (principal_kind IN ('oauth_client','legacy_token','local_cli','local_stdio','application')),
    principal_id text NOT NULL,
    request_id uuid NOT NULL,
    operation text NOT NULL,
    source_id text NOT NULL,
    source_incarnation uuid NOT NULL,
    page_id integer,
    slug text NOT NULL,
    worktree_id uuid REFERENCES persistence_worktrees(id),
    topology_generation bigint,
    digest text NOT NULL,
    intent jsonb,
    authority jsonb NOT NULL,
    sequence bigserial NOT NULL UNIQUE,
    state text NOT NULL DEFAULT 'queued' CHECK (state IN ('queued','running','recovering','committed','conflict','failed','cancelled')),
    execution_token uuid,
    claim_expires_at timestamptz,
    recovery jsonb,
    recovery_bytes bigint NOT NULL DEFAULT 0,
    intent_bytes bigint NOT NULL,
    terminal_reservation bigint NOT NULL,
    outcome jsonb,
    error_code text,
    error_message text,
    blocked_reason text,
    compacted boolean NOT NULL DEFAULT false,
    publication_started boolean NOT NULL DEFAULT false,
    created_at timestamptz NOT NULL DEFAULT now(),
    updated_at timestamptz NOT NULL DEFAULT now(),
    completed_at timestamptz,
    UNIQUE(principal_kind,principal_id,request_id)
  )`,
  `CREATE INDEX IF NOT EXISTS persistence_requests_pending ON persistence_requests(worktree_id,sequence)
    WHERE state IN ('queued','running','recovering')`,
  PERSISTENCE_REQUEST_RECOVERY_INDEX_SQL,
  PERSISTENCE_DATABASE_PENDING_INDEX_SQL,
  PERSISTENCE_SYNC_RUN_OPEN_INDEX_SQL,
  PERSISTENCE_SYNC_RUN_COMMITTED_INDEX_SQL,
  PERSISTENCE_SYNC_WATERMARK_INDEX_SQL,
  PERSISTENCE_COMPACTABLE_INDEX_SQL,
  PERSISTENCE_REQUEST_SLUG_INTENT_INDEX_SQL,
  PERSISTENCE_REQUEST_ID_INDEX_SQL,
  PERSISTENCE_FOREGROUND_COMMITTED_INDEX_SQL,
  PERSISTENCE_REQUEST_REPLAY_ID_INDEX_SQL,
  PERSISTENCE_REQUEST_SLUG_SEQUENCE_INDEX_SQL,
  `CREATE INDEX IF NOT EXISTS persistence_requests_principal ON persistence_requests(principal_kind,principal_id,sequence DESC)`,
  `CREATE TABLE IF NOT EXISTS persistence_effects (
    id bigserial PRIMARY KEY,
    request_id uuid NOT NULL REFERENCES persistence_requests(id),
    kind text NOT NULL,
    revision uuid,
    data jsonb NOT NULL,
    state text NOT NULL DEFAULT 'queued' CHECK (state IN ('queued','running','committed','failed')),
    execution_token uuid,
    updated_at timestamptz NOT NULL DEFAULT now(),
    UNIQUE(request_id,kind)
  )`,
  PERSISTENCE_CONSUMERS_TABLE_SQL,
  MANAGED_WRITER_GUARD_SQL,
] as const;

/**
 * #5182: the per-host Git-durability opt-in column, added by v234 on an
 * existing brain. Deliberately NOT part of the schema statement list: a fresh
 * install gets the column from CREATE TABLE above, and replaying an ALTER on
 * every init would take an ACCESS EXCLUSIVE lock on the bindings table each
 * time the schema blob runs. NULL means "not recorded" (legacy hook probe
 * decides); 'enabled'/'disabled' is the operator's explicit setting.
 */
export const PERSISTENCE_GIT_DURABILITY_COLUMN_SQL = `ALTER TABLE persistence_host_bindings ADD COLUMN IF NOT EXISTS git_durability text CHECK (git_durability IN ('enabled','disabled'))`;