Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* v0.29.1 — Compute a page's effective_date from frontmatter precedence.
*
* The "effective date" is the answer to "when was this page about?" It's
* NOT updated_at (which churns from auto-link) and NOT created_at (which
* is the row insert time). It's the user's stated content date.
*
* Precedence chain (default order):
* 1. frontmatter.event_date — meeting / event pages
* 2. frontmatter.date — dated essays
* 3. frontmatter.published — writing/
* 4. filename-date — leading YYYY-MM-DD in basename
* 5. frontmatter created keys — created / created_at / date_created
* 6. created_at — fallback: the stable creation anchor
* 7. updated_at — last resort
*
* Per-prefix override: for `daily/` and `meetings/` slug prefixes, the
* filename-date jumps to position 1 — the filename is the user's primary
* signal there ("daily/2024-03-15.md" the FILE date matters more than any
* frontmatter the user pasted).
*
* Returns BOTH the parsed Date and the source label so the doctor's
* `effective_date_health` check can detect "fell back to updated_at" rows
* that look populated but are functionally equivalent to a NULL.
*
* Range validation: an explicit frontmatter date (event_date, date,
* published, created keys) written as a calendar date, datetime or YAML date
* accepts any year >= 1 up to NOW + 1 year, so historical works keep their
* real date; the epoch-0 and 0001-01-01 placeholders are dropped. Inferred
* dates (the filename, loosely parsed free text, bare numbers) and the
* fallback timestamps must be in [1990-01-01, NOW + 1 year]. Out-of-range
* values are dropped (the chain falls through to the next element). NaN /
* unparseable strings drop the same way. Timeline entries keep their own
* 1900-2199 window (src/core/ops/timeline.ts).
*
* Pure function. No DB. Tested in test/effective-date.test.ts.
*/
import type { EffectiveDateSource } from './types.ts';
export interface EffectiveDateResult {
date: Date | null;
source: EffectiveDateSource | null;
}
export interface ComputeEffectiveDateOpts {
slug: string;
frontmatter: Record<string, unknown>;
/** `brain.timezone`: IANA zone for offset-less datetimes. Unset or invalid = UTC. */
timeZone?: string;
/** Basename without extension, e.g. "2024-03-15-acme-call". May be null/empty. */
filename?: string | null;
updatedAt: Date;
createdAt: Date;
}
/**
* Slug prefixes where the filename date wins over frontmatter dates. The
* user's primary signal in these directories is the filename, not arbitrary
* frontmatter the importer might have copied.
*
* Hardcoded in v0.29.1 (commit 2). v0.29.1 commit 5 introduces the
* recency-decay map; we could move this list there if we wanted user-tunable
* filename-first prefixes, but the daily/ + meetings/ defaults are stable
* enough that hardcoding is correct.
*/
const FILENAME_FIRST_PREFIXES = ['daily/', 'meetings/'];
/** Creation-date keys Obsidian and Notion exports carry; a content date after the others. */
const CREATED_KEYS = ['created', 'created_at', 'date_created', 'date created'];
/**
* The fallback anchor for an undated page: a page that already fell back
* keeps its stored date, a new file-backed page takes the earliest of its
* file's birth time, modification time and (when opted in) git first-commit
* date, and anything else takes the row's creation time. Never the time of
* the latest write.
*/
export function fallbackCreatedAt(opts: {
existing?: { effective_date?: Date | string | null; effective_date_source?: string | null; created_at?: Date | string | null } | null;
fileTimes?: { birthtime?: Date; mtime?: Date; firstCommit?: Date } | null;
now: Date;
}): Date {
const { existing, fileTimes, now } = opts;
if (existing?.effective_date_source === 'fallback' && existing.effective_date) return new Date(existing.effective_date);
if (existing?.created_at) return new Date(existing.created_at);
const times = [fileTimes?.birthtime, fileTimes?.mtime, fileTimes?.firstCommit]
.filter((d): d is Date => d instanceof Date && d.getTime() > 0)
.map(d => d.getTime());
return times.length ? new Date(Math.min(...times)) : now;
}
const MIN_DATE_MS = Date.UTC(1990, 0, 1);
const FILENAME_DATE_RE = /^(\d{4}-\d{2}-\d{2})/;
function maxDateMs(): number {
// NOW + 1 year, computed at call time so tests with a mocked Date.now()
// see a moving boundary. Pages dated > 1 year in the future are almost
// always corrupt (epoch math gone wrong, typoed century, bad parse).
return Date.now() + 365 * 24 * 60 * 60 * 1000;
}
const MONTHS: Record<string, number> = {
jan: 1, january: 1, feb: 2, february: 2, mar: 3, march: 3, apr: 4, april: 4, may: 5, jun: 6, june: 6,
jul: 7, july: 7, aug: 8, august: 8, sep: 9, sept: 9, september: 9, oct: 10, october: 10,
nov: 11, november: 11, dec: 12, december: 12,
};
const NUMERIC_DATE_RE = /^(\d{4})[-/.](\d{1,2})[-/.](\d{1,2})$/;
const DATETIME_RE = /^(\d{4})-(\d{2})-(\d{2})[T ](\d{2}):(\d{2})(?::(\d{2})(\.\d+)?)?\s*(Z|[+-]\d{2}:?\d{2})?$/i;
const MONTH_DAY_YEAR_RE = /^(?:[a-z]+,?\s+)?([a-z]{3,9})\.?\s+(\d{1,2})(?:st|nd|rd|th)?,?\s+(\d{4})$/i;
const DAY_MONTH_YEAR_RE = /^(\d{1,2})(?:st|nd|rd|th)?\s+([a-z]{3,9})\.?,?\s+(\d{4})$/i;
/** Chat-export style "1:56 pm on 8 May, 2023": the clock time is dropped and the date parsed. */
const TIME_ON_PREFIX_RE = /^\d{1,2}:\d{2}\s*(?:am|pm)?\s+on\s+/i;
/** A UTC calendar date, or null when Y/M/D does not name a real day (2024-02-30). */
function utcCalendarDate(year: number, month: number, day: number, h = 0, m = 0, sec = 0, ms = 0): Date | null {
const d = new Date(Date.UTC(2000, 0, 1, h, m, sec, ms));
d.setUTCFullYear(year, month - 1, day);
return d.getUTCFullYear() === year && d.getUTCMonth() === month - 1 && d.getUTCDate() === day ? d : null;
}
/**
* Marks a frontmatter Date the YAML parser built from an offset-less datetime
* (`2024-03-15T10:00:00`): its UTC fields hold the author's wall-clock time.
*/
export const NAIVE_DATETIME = Symbol.for('gbrain.naive-datetime');
/** Whether `timeZone` names an IANA zone this runtime knows. */
export function isValidTimeZone(timeZone: string): boolean {
try {
new Intl.DateTimeFormat('en-US', { timeZone }).format();
return true;
} catch {
return false;
}
}
/** The calendar day an instant falls on in `timeZone`, as YYYY-MM-DD. */
export function dayInZone(instant: Date, timeZone: string): string {
return new Intl.DateTimeFormat('en-CA', { timeZone, year: 'numeric', month: '2-digit', day: '2-digit' }).format(instant);
}
/**
* The one rule for rendering a stored date as YYYY-MM-DD (think's `<page
* date>`, C1 evidence headers): exactly midnight UTC is a day-only date and
* renders as written; any other instant renders in `timeZone`
* (`brain.timezone`; UTC when unset or invalid). Null for a missing or
* invalid value. Which date to render (content vs observation) is the
* caller's choice.
*/
export function formatBrainDay(value: Date | string | null | undefined, timeZone?: string | null): string | null {
if (value === null || value === undefined || value === '') return null;
const d = value instanceof Date ? value : new Date(value);
if (!Number.isFinite(d.getTime())) return null;
const iso = d.toISOString();
if (iso.endsWith('T00:00:00.000Z')) return iso.slice(0, 10);
return dayInZone(d, timeZone && isValidTimeZone(timeZone) ? timeZone : 'UTC');
}
/** The instant a wall-clock time (held in `wall`'s UTC fields) names in `timeZone`, DST included. */
function zonedWallTime(wall: Date, timeZone: string): Date {
const format = new Intl.DateTimeFormat('en-US', { timeZone, hourCycle: 'h23', year: 'numeric', month: 'numeric',
day: 'numeric', hour: 'numeric', minute: 'numeric', second: 'numeric' });
const offsetAt = (instant: number) => {
const part = (type: string) => +format.formatToParts(instant).find(p => p.type === type)!.value;
return Date.UTC(part('year'), part('month') - 1, part('day'), part('hour'), part('minute'), part('second')) - (instant - instant % 1000);
};
const first = wall.getTime() - offsetAt(wall.getTime());
return new Date(wall.getTime() - offsetAt(first));
}
/**
* Parse a frontmatter value as a Date. Returns null on any failure.
*
* Calendar shapes never depend on the syncing host's timezone: date-only
* values (`2024-03-15`, `2024/03/15`, `March 5, 2024`, `5 March 2024`) are UTC
* calendar dates, and a datetime without an offset is read in `timeZone`
* (the brain's `brain.timezone`; UTC when unset). A calendar-invalid date
* (`2024-02-30`) is rejected rather than rolled over. Other strings fall back
* to Date.parse.
*/
export function parseDateLoose(value: unknown, timeZone?: string): Date | null {
if (value == null) return null;
const zone = timeZone && timeZone !== 'UTC' ? timeZone : null;
if (value instanceof Date) {
if (!Number.isFinite(value.getTime())) return null;
return zone && (value as Date & { [NAIVE_DATETIME]?: boolean })[NAIVE_DATETIME] ? zonedWallTime(value, zone) : value;
}
if (typeof value === 'string') {
const trimmed = value.trim();
if (trimmed === '') return null;
const numeric = NUMERIC_DATE_RE.exec(trimmed);
if (numeric) return utcCalendarDate(+numeric[1], +numeric[2], +numeric[3]);
const datetime = DATETIME_RE.exec(trimmed);
if (datetime) {
const [, y, mo, d, h, mi, sec, frac, offset] = datetime;
const wall = utcCalendarDate(+y, +mo, +d, +h, +mi, +(sec ?? 0), frac ? Math.round(+frac * 1000) : 0);
if (!wall || +h > 23 || +mi > 59 || +(sec ?? 0) > 59) return null;
if (!offset) return zone ? zonedWallTime(wall, zone) : wall;
if (offset.toUpperCase() === 'Z') return wall;
const sign = offset.startsWith('-') ? -1 : 1;
const [zh, zm] = [+offset.slice(1, 3), +offset.slice(-2)];
return new Date(wall.getTime() - sign * (zh * 60 + zm) * 60_000);
}
const dated = trimmed.replace(TIME_ON_PREFIX_RE, '');
const mdy = MONTH_DAY_YEAR_RE.exec(dated);
if (mdy && MONTHS[mdy[1].toLowerCase()]) return utcCalendarDate(+mdy[3], MONTHS[mdy[1].toLowerCase()], +mdy[2]);
const dmy = DAY_MONTH_YEAR_RE.exec(dated);
if (dmy && MONTHS[dmy[2].toLowerCase()]) return utcCalendarDate(+dmy[3], MONTHS[dmy[2].toLowerCase()], +dmy[1]);
const ms = Date.parse(trimmed);
if (!Number.isFinite(ms)) return null;
return new Date(ms);
}
if (typeof value === 'number') {
// Plausibility: numbers are usually ms since epoch but YAML can yield
// bare integers (year? month? day?) — accept only if the resulting Date
// falls inside the valid window. validateInRange catches the rest.
return Number.isFinite(value) ? new Date(value) : null;
}
return null;
}
function validateInRange(d: Date | null): Date | null {
if (d === null) return null;
const ms = d.getTime();
if (!Number.isFinite(ms)) return null;
if (ms < MIN_DATE_MS) return null;
if (ms > maxDateMs()) return null;
return d;
}
/**
* #5742: an explicit frontmatter date in a structured shape keeps any year >= 1
* (up to NOW + 1 year) except the epoch-0 and 0001-01-01 placeholders. Loosely
* parsed strings and bare numbers are inference, so they keep the 1990 floor.
*/
function validateExplicit(value: unknown, timeZone?: string): Date | null {
const d = parseDateLoose(value, timeZone);
const structured = value instanceof Date || (typeof value === 'string'
&& [NUMERIC_DATE_RE, DATETIME_RE, MONTH_DAY_YEAR_RE, DAY_MONTH_YEAR_RE].some(re => re.test(value.trim().replace(TIME_ON_PREFIX_RE, ''))));
if (!structured) return validateInRange(d);
if (d === null) return null;
const ms = d.getTime();
if (!Number.isFinite(ms) || ms === 0 || ms > maxDateMs()) return null;
const year = d.getUTCFullYear();
if (year < 1 || (year === 1 && d.getUTCMonth() === 0 && d.getUTCDate() === 1)) return null;
return d;
}
function extractFilenameDate(filename: string | null | undefined): Date | null {
if (!filename) return null;
const m = filename.match(FILENAME_DATE_RE);
if (!m) return null;
return validateInRange(parseDateLoose(m[1]));
}
function hasFilenameFirstPrefix(slug: string): boolean {
for (const p of FILENAME_FIRST_PREFIXES) {
if (slug.startsWith(p)) return true;
}
return false;
}
/**
* Run the precedence chain. Returns the first valid (in-range) date and its
* source label. Falls all the way through to updated_at / created_at as
* 'fallback' when nothing in frontmatter or filename parses.
*/
export function computeEffectiveDate(opts: ComputeEffectiveDateOpts): EffectiveDateResult {
const { slug, frontmatter, filename, updatedAt, createdAt } = opts;
const filenameFirst = hasFilenameFirstPrefix(slug);
const timeZone = opts.timeZone && isValidTimeZone(opts.timeZone) ? opts.timeZone : undefined;
const fmEvent = validateExplicit(frontmatter.event_date, timeZone);
const fmDate = validateExplicit(frontmatter.date, timeZone);
const fmPublished = validateExplicit(frontmatter.published, timeZone);
const filenameDate = extractFilenameDate(filename);
const fmCreated = CREATED_KEYS.map(key => validateExplicit(frontmatter[key], timeZone)).find(d => d !== null) ?? null;
// Build the ordered candidate list. For filename-first prefixes
// (daily/, meetings/) the filename moves to the head of the chain.
const candidates: Array<{ date: Date | null; source: EffectiveDateSource }> = filenameFirst
? [
{ date: filenameDate, source: 'filename' },
{ date: fmEvent, source: 'event_date' },
{ date: fmDate, source: 'date' },
{ date: fmPublished, source: 'published' },
{ date: fmCreated, source: 'created' },
]
: [
{ date: fmEvent, source: 'event_date' },
{ date: fmDate, source: 'date' },
{ date: fmPublished, source: 'published' },
{ date: filenameDate, source: 'filename' },
{ date: fmCreated, source: 'created' },
];
for (const c of candidates) {
if (c.date !== null) return { date: c.date, source: c.source };
}
// Fallback chain: the creation anchor, then updated_at. The anchor is
// stable across edits (see fallbackCreatedAt), so an undated page keeps its
// date instead of taking every write's time. Both are guaranteed non-null
// by the schema; the validation here is defensive against bad fixtures.
const cre = validateInRange(createdAt);
if (cre !== null) return { date: cre, source: 'fallback' };
const upd = validateInRange(updatedAt);
if (upd !== null) return { date: upd, source: 'fallback' };
return { date: null, source: null };
}