Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* The fence repair validator (#6188): the one gate every tier's output
* passes before anything is written.
*
* (a) still_invalid the after page compiles (strict parse, markers, unique rows)
* (e) row_count_changed same data-row count; every before row sits in the after fence
* (b) claim_changed claim cells identical, in order (strikethrough kept, whitespace collapsed)
* (c) row_number_changed every valid, page-unique row number keeps its claim
* (d) visibility_loosened a private row never becomes world; invalid becomes world only via `public` on a world page
* (f) cell_changed per row, a valid non-claim cell keeps its column and text; a misaligned cell may move
* with its text unchanged; text changes only where an issue names the row and column
* and a named rule produced it (TE2)
* (g) protection_loosened nothing the privacy boundary hid is shown after, except the trailing lines of a fence a
* `close_fence_trailing` fix closed (#6377): the structural rule admits that fix only on a private
* page or under the user's hash-bound approval, and the gate accepts exactly those lines
*
* Gates (b), (c), (e) and (f) read the raw-row extraction of the
* before-region, never strict-parser output. (e) runs before (b) so a dropped
* or stranded row reports the row-count gate. Failures carry the reason, the
* gate letter and row numbers only.
*
* Before rows pair with after rows by occurrence in the primary fence. When
* the fixes name `merge_fences` for a section and kind (#6377), the pairing
* is the merge mapping re-derived from the before page (`merge.ts`): every
* fence's rows in document order, each kept at its merged occurrence or
* dropped as an exact duplicate of a kept row. Gate (e) then accepts exactly
* the dropped rows, each only when its cells equal the kept row's cells as
* written; the other gates run row by row through the mapping; a
* `superseded by #N` reference in a merged row may read the new number of
* its own before-fence's row N. Without a merge fix nothing changes.
*/
import { mergePlans, rowKey, type MergePlan } from './merge.ts';
import { normalizeFences } from './normalize.ts';
import { exposedLines, sectionsOf, strictFailures } from './page-checks.ts';
import { extractRawRows, primaryFence, rowNumOf, type RawFence, type RawRow } from './raw-rows.ts';
import { trailingLinesOf } from './structure.ts';
import { cellsChanged } from './validate-cells.ts';
import { GATE_REASONS } from './reasons.ts';
import { cellValid, collapse, enumSynonym, supersededRef } from './schema.ts';
import type { FenceCtx, FenceKind, FenceLocation, FencePage, FenceReason, FenceSection, FenceTier, GateLetter } from './types.ts';
export interface ValidateCtx extends FenceCtx {
/** The tier whose output is checked. */
tier: Exclude<FenceTier, 'manual'>;
/** Issues and fixes found on the before page; a cell may change only where one names it. */
issues: readonly FenceLocation[];
}
export type ValidateResult =
| { ok: true }
| {
ok: false;
reason: FenceReason;
gate: GateLetter;
tier: Exclude<FenceTier, 'manual'>;
fence: FenceKind | null;
section: FenceSection | null;
rows: number[];
};
/** One before row and the after row it pairs with (null for a dropped duplicate). */
interface Paired {
row: RawRow;
/** The before fence holding the row. */
fence: RawFence;
after: RawRow | null;
/** The before row an exact duplicate was dropped for. */
duplicateOf: Paired | null;
}
/** One fence kind in one section, before and after. */
export interface FencePair {
section: FenceSection;
kind: FenceKind;
before: RawFence | null;
after: RawFence | null;
/** Every before row in document order (all fences of the kind under a merge). */
rows: Paired[];
}
type Failure = { gate: GateLetter; fence: FenceKind | null; section: FenceSection | null; rows: number[] };
const at = (pair: FencePair, gate: GateLetter, rows: number[]): Failure => ({ gate, fence: pair.kind, section: pair.section, rows });
export function validateFenceRepair(before: FencePage, after: FencePage, ctx: ValidateCtx): ValidateResult {
const failure = firstFailure(before, after, ctx);
if (!failure) return { ok: true };
return {
ok: false, reason: GATE_REASONS[failure.gate], gate: failure.gate, tier: ctx.tier,
fence: failure.fence, section: failure.section, rows: [...new Set(failure.rows)],
};
}
/** The page is a Tier 1 fixed point: normalizing it applies no fix. */
export function isFenceFixedPoint(page: FencePage, ctx: FenceCtx): boolean {
return normalizeFences(page, ctx).fixes.length === 0;
}
function firstFailure(before: FencePage, after: FencePage, ctx: ValidateCtx): Failure | null {
const strict = strictFailures(after);
if (strict.length) {
const f = strict[0]!;
return { gate: 'a', fence: f.fence, section: f.section, rows: f.rows };
}
const pairs = fencePairs(before, after, ctx);
if (!pairs) return { gate: 'e', fence: null, section: null, rows: [] };
for (const check of [rowCount, claims, rowNumbers, visibility, cells]) {
const failed = check(pairs, ctx);
if (failed) return failed;
}
return protection(before, after, ctx);
}
/** Null when the fixes name a merge the before page does not admit (nothing the mapping could vouch for). */
function fencePairs(before: FencePage, after: FencePage, ctx: ValidateCtx): FencePair[] | null {
const merges = mergePlans(before, ctx.issues.flatMap(i => ('class' in i && typeof i.class === 'string' ? [{ fence: i.fence, section: i.section, class: i.class }] : [])));
if (!merges) return null;
const afterSections = new Map(sectionsOf(after));
return sectionsOf(before).flatMap(([section, text]) => {
const b = extractRawRows(text, section);
const a = extractRawRows(afterSections.get(section) ?? '', section);
return (['facts', 'takes'] as const).map(kind => {
const pair: FencePair = { section, kind, before: primaryFence(b, kind), after: primaryFence(a, kind), rows: [] };
const plan = merges.get(`${section}:${kind}`);
pair.rows = plan ? mergedRows(plan, pair.after) : rowsOf(pair.before).map(row => ({ row, fence: pair.before!, after: rowsOf(pair.after)[row.occurrence] ?? null, duplicateOf: null }));
return pair;
});
});
}
function mergedRows(plan: MergePlan, after: RawFence | null): Paired[] {
const afterRows = rowsOf(after);
const paired: Paired[] = [];
for (const r of plan.rows) {
paired.push({ row: r.row, fence: plan.fences[r.fence]!, after: r.keptAs === null ? null : afterRows[r.keptAs] ?? null, duplicateOf: r.duplicateOf === null ? null : paired[r.duplicateOf]! });
}
return paired;
}
const rowsOf = (fence: RawFence | null): RawRow[] => fence?.rows ?? [];
const numOf = (fence: RawFence | null, row: RawRow | undefined | null): number | null => (fence && row ? rowNumOf(fence, row) : null);
const claimOf = (row: RawRow): string => collapse(row.byColumn.get('claim')?.text ?? '');
function numbers(fence: RawFence | null, rows: readonly RawRow[]): number[] {
return rows.map(r => numOf(fence, r)).filter((n): n is number => n !== null);
}
/** (e) */
function rowCount(pairs: FencePair[]): Failure | null {
for (const pair of pairs) {
const kept = pair.rows.filter(p => p.duplicateOf === null);
const a = rowsOf(pair.after);
if (kept.length !== a.length) {
const longer = kept.length > a.length ? { fence: pair.before, rows: kept.map(p => p.row) } : { fence: pair.after, rows: a };
return at(pair, 'e', numbers(longer.fence, longer.rows.slice(Math.min(a.length, kept.length))));
}
// A dropped row is admitted only as an exact copy of its kept row, as both were written.
const dropped = pair.rows.filter(p => p.duplicateOf !== null && rowKey(p.fence, p.row) !== rowKey(p.duplicateOf!.fence, p.duplicateOf!.row));
if (dropped.length) return at(pair, 'e', dropped.map(p => numOf(p.fence, p.row)).filter((n): n is number => n !== null));
}
return null;
}
/** (b) */
function claims(pairs: FencePair[]): Failure | null {
for (const pair of pairs) {
const changed = pair.rows.filter(p => p.after && claimOf(p.row) !== claimOf(p.after));
if (changed.length) return at(pair, 'b', numbers(pair.after, changed.map(p => p.after!)));
}
return null;
}
/** (c) */
function rowNumbers(pairs: FencePair[]): Failure | null {
for (const kind of ['facts', 'takes'] as const) {
const of = pairs.filter(p => p.kind === kind);
const before = of.flatMap(p => p.rows.map(r => ({ num: numOf(r.fence, r.row), claim: claimOf(r.row), dropped: r.duplicateOf !== null, pair: p })));
const after = new Set(of.flatMap(p => rowsOf(p.after).map(row => `${numOf(p.after, row)}\u0000${claimOf(row)}`)));
for (const row of before) {
if (row.num === null || row.dropped || before.filter(r => r.num === row.num).length > 1) continue;
if (!after.has(`${row.num}\u0000${row.claim}`)) return at(row.pair, 'c', [row.num]);
}
}
return null;
}
/** (d) */
function visibility(pairs: FencePair[], ctx: ValidateCtx): Failure | null {
for (const pair of pairs.filter(p => p.kind === 'facts')) {
for (const p of pair.rows) {
if (!p.after || p.after.byColumn.get('visibility')?.text.trim().toLowerCase() !== 'world') continue;
if (!mayBecomeWorld(p.row, ctx)) return at(pair, 'd', numbers(pair.after, [p.after]));
}
}
return null;
}
function mayBecomeWorld(row: RawRow, ctx: ValidateCtx): boolean {
const toWorld = (text: string) => enumSynonym('visibility', text, ctx.pageVisibility) === 'world';
const aligned = !row.beforeHeader && row.shape === 'ok';
if (!aligned) return [...row.byColumn.values(), ...row.extra].some(c => toWorld(c.text));
const vis = row.byColumn.get('visibility');
if (!vis) return false;
return cellValid('facts', 'visibility', vis.text) ? vis.text.trim().toLowerCase() === 'world' : toWorld(vis.text);
}
/** (f) */
function cells(pairs: FencePair[], ctx: ValidateCtx): Failure | null {
for (const pair of pairs) {
for (const p of pair.rows) {
if (!p.after) continue;
if (cellsChanged(pair, withFollowedRef(pair, p), p.after, ctx).length) return at(pair, 'f', numbers(pair.after, [p.after]));
}
}
return null;
}
/**
* Under a merge, a `superseded by #N` reference in a before row may follow
* the one row numbered N of the row's own before fence (kept, or the kept
* row its exact duplicate equalled) to that row's after number: the before
* row is compared as if written with the new number. Any other reference
* change fails gate (f) as a changed cell.
*/
function withFollowedRef(pair: FencePair, p: Paired): RawRow {
if (pair.rows.every(r => r.fence === pair.before)) return p.row;
const column = pair.kind === 'facts' ? 'context' : 'source';
const cell = p.row.byColumn.get(column);
const ref = cell ? supersededRef(cell.text) : null;
if (ref === null) return p.row;
const own = pair.rows.filter(r => r.fence === p.fence && numOf(r.fence, r.row) === ref);
if (own.length !== 1) return p.row;
const target = own[0]!.duplicateOf ?? own[0]!;
const now = numOf(pair.after, target.after);
if (now === null || now === ref) return p.row;
const rewrite = (text: string) => text.replace(/(superseded by #)\d+/i, `$1${now}`);
const followed = { ...cell!, text: rewrite(cell!.text), raw: rewrite(cell!.raw) };
const byColumn = new Map(p.row.byColumn);
byColumn.set(column, followed);
return { ...p.row, byColumn, cells: p.row.cells.map(c => (c === cell ? followed : c)) };
}
/** (g) */
function protection(before: FencePage, after: FencePage, ctx: ValidateCtx): Failure | null {
const afterSections = new Map(sectionsOf(after));
for (const [section, text] of sectionsOf(before)) {
const exposed = exposedLines(text, afterSections.get(section) ?? '');
if (!exposed.length) continue;
const closed = ctx.issues.filter((i): i is FenceLocation & { class: 'close_fence_trailing' } => 'class' in i && i.class === 'close_fence_trailing' && i.section === section);
if (!closed.length) return { gate: 'g', fence: null, section, rows: [] };
const allowed = new Map<string, number>();
const tails = trailingLinesOf(text, section);
for (const fix of closed) for (const line of tails.get(`${section}:${fix.fence}`) ?? []) allowed.set(line, (allowed.get(line) ?? 0) + 1);
for (const line of exposed) {
const left = allowed.get(line) ?? 0;
if (left <= 0) return { gate: 'g', fence: closed[0]!.fence, section, rows: [] };
allowed.set(line, left - 1);
}
}
return null;
}