Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
11.7 KB
Raw Blame
/**
 * delta's per-arm cursor (contributor audit wave P0). Pages page by the
 * keyset `(updated_at, slug)`, facts by `(created_at, id)`, both at column
 * (microsecond) precision. Each arm advances through the prefix it actually
 * delivered and no further; an arm whose result is unknown does not move.
 *
 * The opaque `cursor` request param carries both keysets; the legacy
 * `since`/`slug` pair stays conservative so an older client re-sees pages but
 * never skips facts. Pure: no engine access.
 */

/** Pages arm position. `slug` undefined = strictly after `since` (a legacy stateless call). */
export interface PagesPos { since: string; slug?: string }
/** Facts arm position. `id` null = strictly after `at` (a legacy `since`). */
export interface FactsPos { at: string; id: number | null }
export interface DeltaPosition { pages: PagesPos; facts: FactsPos }

/** Rows committed in a transaction that started before this lag can still be missed (documented bound). */
export const DELTA_COMMIT_LAG_MS = 2_000;
export const DELTA_TIMESTAMP_RANGE = '0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999Z';

const MICRO_ISO = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.(\d{1,6}))?Z$/;

/** Normalize an ISO UTC timestamp to the 6-digit `…ss.ffffffZ` shape so lexicographic order is time order. */
export function toMicroIso(iso: string): string {
  const m = MICRO_ISO.exec(iso);
  if (m) return `${m[1]}-${m[2]}-${m[3]}T${m[4]}:${m[5]}:${m[6]}.${(m[7] ?? '').padEnd(6, '0')}Z`;
  return toMicroIso(new Date(Date.parse(iso)).toISOString());
}

/** Microseconds since the epoch, exact (BigInt) for a micro-ISO string. */
function toMicros(iso: string): bigint {
  const m = toMicroIso(iso);
  return BigInt(Date.parse(`${m.slice(0, 19)}Z`)) * 1000n + BigInt(m.slice(20, 26));
}

function fromMicros(us: bigint): string {
  const ms = us / 1000n - (us % 1000n < 0n ? 1n : 0n);
  const rem = us - ms * 1000n;
  const base = new Date(Number(ms)).toISOString();
  return `${base.slice(0, 23)}${String(rem).padStart(3, '0')}Z`;
}

/** One microsecond earlier: the strictly-earlier clamp at column precision. */
export function microBefore(iso: string): string {
  return fromMicros(toMicros(iso) - 1n);
}

export function horizonIso(now: number = Date.now()): string {
  return toMicroIso(new Date(now - DELTA_COMMIT_LAG_MS).toISOString());
}

/**
 * Validate a timestamp the way delta's `since` is validated: parseable,
 * a real calendar date, and inside 0001-9999 on the PARSED (UTC) value,
 * so an offset cannot smuggle year 0 or an extended year past the check.
 * Returns the canonical form or an error message.
 */
export function checkDeltaTimestamp(raw: string): { ok: true; value: string } | { ok: false; why: 'unparseable' | 'calendar' | 'range' } {
  const ms = Date.parse(raw);
  if (!Number.isFinite(ms)) return { ok: false, why: 'unparseable' };
  if (/^[+-]/.test(raw.trim())) return { ok: false, why: 'range' };
  const iso = raw.match(/^(\d{4})-(\d{2})-(\d{2})T/);
  if (iso) {
    const [year, month, day] = iso.slice(1).map(Number);
    const leap = year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
    const dim = [31, leap ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
    if (month < 1 || month > 12 || day < 1 || day > dim[month - 1]) return { ok: false, why: 'calendar' };
  }
  const year = new Date(ms).getUTCFullYear();
  if (year < 1 || year > 9999) return { ok: false, why: 'range' };
  return {
    ok: true,
    value: /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{6}Z$/.test(raw) ? raw : new Date(ms).toISOString(),
  };
}

/** Total order on pages positions; an undefined slug sorts after every slug at that timestamp. */
export function comparePages(a: PagesPos, b: PagesPos): number {
  const t = toMicroIso(a.since).localeCompare(toMicroIso(b.since));
  if (t !== 0) return t;
  if (a.slug === b.slug) return 0;
  if (a.slug === undefined) return 1;
  if (b.slug === undefined) return -1;
  return a.slug < b.slug ? -1 : 1;
}

/** Total order on facts positions; a null id sorts after every id at that timestamp. */
export function compareFacts(a: FactsPos, b: FactsPos): number {
  const t = toMicroIso(a.at).localeCompare(toMicroIso(b.at));
  if (t !== 0) return t;
  if (a.id === b.id) return 0;
  if (a.id === null) return 1;
  if (b.id === null) return -1;
  return a.id < b.id ? -1 : 1;
}

const maxPages = (a: PagesPos, b: PagesPos) => (comparePages(a, b) >= 0 ? a : b);
const maxFacts = (a: FactsPos, b: FactsPos) => (compareFacts(a, b) >= 0 ? a : b);

/** Opaque wire form: base64url JSON `{v:1, p:[since, slug], f:[at, id]}`. */
export function encodeDeltaCursor(pos: DeltaPosition): string {
  const body = { v: 1, p: [pos.pages.since, pos.pages.slug ?? null], f: [pos.facts.at, pos.facts.id] };
  return Buffer.from(JSON.stringify(body), 'utf8').toString('base64url');
}

const MAX_CURSOR_LEN = 2_048;
const MAX_SLUG_LEN = 512;

/** Decode + validate a `cursor` param. Returns the position or the reason it was refused. */
export function decodeDeltaCursor(raw: string): { ok: true; pos: DeltaPosition } | { ok: false; why: string } {
  if (raw.length > MAX_CURSOR_LEN || !/^[A-Za-z0-9_-]+$/.test(raw)) return { ok: false, why: 'not a cursor returned by delta (expected base64url)' };
  let body: unknown;
  try {
    body = JSON.parse(Buffer.from(raw, 'base64url').toString('utf8'));
  } catch {
    return { ok: false, why: 'not a cursor returned by delta (undecodable)' };
  }
  const b = body as { v?: unknown; p?: unknown; f?: unknown };
  if (!b || typeof b !== 'object' || b.v !== 1 || !Array.isArray(b.p) || !Array.isArray(b.f) || b.p.length !== 2 || b.f.length !== 2) {
    return { ok: false, why: 'not a version-1 delta cursor' };
  }
  const [ps, pslug] = b.p as unknown[];
  const [fa, fid] = b.f as unknown[];
  if (typeof ps !== 'string' || typeof fa !== 'string') return { ok: false, why: 'cursor timestamps must be strings' };
  for (const ts of [ps, fa]) {
    const c = checkDeltaTimestamp(ts);
    if (!c.ok) return { ok: false, why: c.why === 'range' ? `cursor timestamp outside ${DELTA_TIMESTAMP_RANGE}` : 'cursor timestamp is not a valid ISO 8601 calendar timestamp' };
  }
  if (pslug !== null && (typeof pslug !== 'string' || pslug.length > MAX_SLUG_LEN)) return { ok: false, why: 'cursor page slug is invalid' };
  if (fid !== null && (typeof fid !== 'number' || !Number.isSafeInteger(fid) || fid < 0)) return { ok: false, why: 'cursor fact id must be a non-negative integer' };
  const canonical = (ts: string) => (checkDeltaTimestamp(ts) as { value: string }).value;
  return {
    ok: true,
    pos: {
      pages: { since: canonical(ps), ...(pslug !== null ? { slug: pslug as string } : {}) },
      facts: { at: canonical(fa), id: fid as number | null },
    },
  };
}

/** Whether an arm's read completed (`ok`), threw (`failed`) or never finished before the deadline (`unknown`). */
export type ArmStatus = 'ok' | 'failed' | 'unknown';

/**
 * Next pages position: through the last DELIVERED page at or before the
 * horizon. An empty, complete, undropped session arm advances to the horizon (rows
 * from a transaction that commits later than the lag can still be missed —
 * the documented bound). Anything else holds.
 */
export function nextPagesPos(input: {
  start: PagesPos;
  complete: boolean;
  delivered: Array<{ updated_at: string; slug: string }>;
  undelivered: boolean;
  horizon: string;
  /** Session callers move an empty, complete arm up to the horizon; a stateless cursor stays put (its caller owns it). */
  advanceOnEmpty: boolean;
}): PagesPos {
  const { start, complete, delivered, undelivered, horizon, advanceOnEmpty } = input;
  if (!complete) return start;
  let next = start;
  for (const p of delivered) {
    if (toMicroIso(p.updated_at) > horizon) return next;
    next = { since: p.updated_at, slug: p.slug };
  }
  if (delivered.length === 0 && !undelivered && advanceOnEmpty) return maxPages(start, { since: horizon, slug: '' });
  return next;
}

export interface RawFactRef { id: number; at: string; repId: number }

/**
 * Next facts position, computed from the RAW rows (duplicate collapse emits a
 * cluster's newest row at its first-seen position): the largest raw row such
 * that every raw row at or below it belongs to a delivered cluster and is at
 * or before the horizon. Also returns the oldest raw row NOT covered, which
 * the conservative legacy cursor must stay strictly before.
 */
export function nextFactsPos(input: {
  start: FactsPos;
  complete: boolean;
  raw: RawFactRef[];
  overflowRow: { id: number; at: string } | null;
  deliveredRepIds: ReadonlySet<number>;
  horizon: string;
  advanceOnEmpty: boolean;
}): { next: FactsPos; oldestUndelivered: string | null } {
  const { start, complete, raw, overflowRow, deliveredRepIds, horizon, advanceOnEmpty } = input;
  if (!complete) return { next: start, oldestUndelivered: null };
  const oldestUndelivered = raw.find((r) => !deliveredRepIds.has(r.repId))?.at ?? overflowRow?.at ?? null;
  if (raw.length === 0 && !overflowRow) return { next: advanceOnEmpty ? maxFacts(start, { at: horizon, id: 0 }) : start, oldestUndelivered };
  let next = start;
  for (const r of raw) {
    if (!deliveredRepIds.has(r.repId) || toMicroIso(r.at) > horizon) break;
    next = { at: r.at, id: r.id };
  }
  return { next, oldestUndelivered };
}

/** Session row fields delta resumes from (see session-state.ts DeltaSessionState). */
interface SessionCursor {
  last_wake_at: string | null;
  cursor_slug: string | undefined;
  facts_cursor_at: string | null;
  facts_cursor_id: number | null;
}

/**
 * Where a delta call starts. Precedence: explicit `cursor` > explicit `since`
 * (both arms strictly after it, slug only when supplied) > the session row
 * (`since_slug` may override its slug) > none (a first wake).
 */
export function resolveDeltaStart(input: {
  cursorPos: DeltaPosition | null;
  explicitSince: string | null;
  explicitSlug: string | undefined;
  session: SessionCursor | null;
}): DeltaPosition | null {
  const { cursorPos, explicitSince, explicitSlug, session } = input;
  if (cursorPos) return cursorPos;
  if (explicitSince) {
    return { pages: { since: explicitSince, ...(explicitSlug !== undefined ? { slug: explicitSlug } : {}) }, facts: { at: explicitSince, id: null } };
  }
  if (!session?.last_wake_at) return null;
  const slug = explicitSlug ?? session.cursor_slug;
  return {
    pages: { since: session.last_wake_at, ...(slug !== undefined ? { slug } : {}) },
    facts: session.facts_cursor_at ? { at: session.facts_cursor_at, id: session.facts_cursor_id } : { at: session.last_wake_at, id: null },
  };
}

/**
 * The conservative single cursor for clients that do not send `cursor`.
 * No advance at all while any arm is failed or unknown; otherwise the last
 * delivered page, or on a page-less wake the newest delivered fact (an old
 * client reads facts strictly after `since`, so a budget that fits only part
 * of the facts still drains them). Never at or past the oldest undelivered
 * fact: it clamps one microsecond before it and resets the slug.
 */
export function legacyDeltaCursor(input: {
  start: DeltaPosition;
  pagesNext: PagesPos;
  factsNext: FactsPos;
  oldestUndelivered: string | null;
  incomplete: boolean;
  pagesDelivered: number;
  factsDelivered: number;
  pagesQuiet: boolean;
}): { legacy: PagesPos; clamped: boolean } {
  const { start, pagesNext, factsNext, oldestUndelivered, incomplete, pagesDelivered, factsDelivered, pagesQuiet } = input;
  if (incomplete) return { legacy: start.pages, clamped: false };
  const legacy: PagesPos =
    pagesDelivered > 0 ? pagesNext
      : pagesQuiet && factsDelivered > 0 && compareFacts(factsNext, start.facts) > 0 ? { since: factsNext.at, slug: '' }
        : start.pages;
  if (oldestUndelivered !== null && toMicroIso(legacy.since) >= toMicroIso(oldestUndelivered)) {
    return { legacy: { since: microBefore(oldestUndelivered), slug: '' }, clamped: true };
  }
  return { legacy, clamped: false };
}