Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* v0.28: parser/renderer for fenced takes tables.
*
* Markdown is the source of truth (git is canonical). The DB takes table
* is a derived index. This module is the boundary between them.
*
* Fence shape (HTML-comment markers, same pattern as skillpack/installer.ts):
*
* ## Takes
*
* <!--- gbrain:takes:begin -->
* | # | claim | kind | who | weight | since | source |
* |---|-------|------|-----|--------|-------|--------|
* | 1 | CEO of Acme | fact | world | 1.0 | 2017-01 | Crustdata |
* | 2 | Strong technical founder | take | alice-example | 0.85 | 2026-04-29 | OH 2026-04-29 |
* | 3 | ~~Will reach $50B~~ | bet | alice-example | 0.7 | 2026-04-29 → 2026-06 | superseded by #4 |
* | 4 | Will reach $30B | bet | alice-example | 0.55 | 2026-06 | revised after Q2 numbers |
* <!--- gbrain:takes:end -->
*
* Parsing rules (Codex P1 #8 fold — strict on canonical, lenient on hand-edits):
*
* - Strict shape (clean header + 8 cells per row including leading/trailing |)
* parses without warning.
* - Strikethrough `~~claim~~` → active=false; the inner text is parsed.
* - Date ranges in `since` (`2022-01 → 2026-06` or `2022-01 -> 2026-06`)
* split into `since_date` + `until_date`.
* - Weight is parsed as float; out-of-range values [0,1] are clamped at the
* engine layer (TAKES_WEIGHT_CLAMPED), not here.
* - Malformed rows (wrong cell count, non-numeric weight, unknown kind) are
* skipped. The fence parser returns the parsed-OK rows + a `warnings` list
* so callers (extract, doctor) can surface `TAKES_TABLE_MALFORMED`.
*
* Append-only semantics (CEO-D6 + eng-D9): `upsertTakeRow` always appends
* to the end of the table. `supersedeRow` strikes through the target row's
* claim + appends a new row. Cross-page refs `slug#N` and synthesis_evidence
* stay valid forever because no row_num ever shifts.
*/
// v0.38: TakeKind opens from closed 4-element union to string (T3 + T10).
// See `src/core/engine.ts` TakeKind for full rationale. Runtime validation
// moves to active schema pack's annotation primitive declarations; the
// pre-v0.38 {fact|take|bet|hunch} seed lives in `gbrain-base.yaml`.
export type TakeKind = string;
export type TakeQuality = 'correct' | 'incorrect' | 'partial' | 'unresolvable';
export interface ParsedTake {
rowNum: number;
claim: string; // strikethrough markers stripped; inner text only
kind: TakeKind;
/**
* Who HOLDS this belief — the person asserting/endorsing it.
* NOT the person the belief is ABOUT (that's the subject, implicit in the claim).
*
* Cross-modal eval (2026-05-10, 3 frontier models on 100K takes) found
* holder/subject confusion was the #1 attribution error (6.5/10).
*
* The test: "Did this person SAY or CLEARLY IMPLY this?"
* YES → holder = people/slug
* NO, it's your analysis of them → holder = brain
*
* Examples:
* ✅ holder=people/alice-example claim="AI will replace 50% of coding" (Alice SAID this)
* ✅ holder=brain claim="Alice has a hero/rescuer pattern" (analysis OF Alice)
* ✅ holder=people/bob-example claim="We can hit $10M ARR" (Bob SAID this)
* ❌ holder=people/alice-example claim="Alice has a hero/rescuer pattern" (not her belief)
* ❌ holder=companies/widgetco-example claim="Latency is 15-20s" (Dana said it → people/dana-example)
*
* Values: 'world' (consensus fact) | 'people/<slug>' (individual's stated belief) |
* 'companies/<slug>' (institutional fact, no individual claimant) |
* 'brain' (AI-inferred when holder is genuinely ambiguous)
*
* Additional rules from production eval:
* - Amplification ≠ endorsement: retweet-only → max weight 0.55
* - Self-reported ≠ verified: "Charlie reports 7 figures" → people/charlie-example, NOT world
* - Founder describing company → people/founder, NOT companies/slug
*/
holder: string;
weight: number; // 0..1 (raw — may be out of range; engine clamps). Prefer 0.05 increments.
sinceDate?: string; // ISO 'YYYY-MM-DD' or 'YYYY-MM' (caller's choice)
untilDate?: string;
source?: string;
active: boolean; // false when claim was wrapped in ~~ ~~
// v0.30.0 (Slice A1) resolution fields. Optional + always undefined on
// unresolved rows. The renderer emits the resolved/quality/evidence/value/
// unit/by columns ONLY when at least one row on the page has resolvedQuality
// set; pages with no resolved rows keep their narrow 7-column shape.
// Round-trip preservation through cmdUpdate/cmdSupersede is the codex F3
// safety net — without it, every update after a resolve silently deletes
// the resolution data on the next render.
resolvedAt?: string; // ISO timestamp 'YYYY-MM-DD' or full ISO
resolvedQuality?: TakeQuality;
resolvedOutcome?: boolean; // back-compat boolean; derivable from quality
resolvedEvidence?: string; // human note (alias for resolved_source)
resolvedValue?: number;
resolvedUnit?: string;
resolvedBy?: string; // slug or 'alice-example'
}
export interface ParseResult {
takes: ParsedTake[];
warnings: string[];
/**
* Row numbers held by reservation rows (`takes remove`, W9F item 4): kept
* in the fence so the number is never handed out again, never a take.
*/
reservedRowNums: number[];
}
/**
* A removed take leaves a reservation row in its place: a fully parsed row
* whose struck claim and source cell carry these markers and whose other
* cells are reset, so `nextFreeRowNum` keeps seeing its number. The parser
* returns it in `reservedRowNums`, never in `takes`.
*/
export const TAKE_RESERVATION_CLAIM = '(removed)';
export const TAKE_RESERVATION_SOURCE = 'removed';
function reservationRow(rowNum: number): ParsedTake {
return { rowNum, claim: TAKE_RESERVATION_CLAIM, kind: 'take', holder: 'world', weight: 0, source: TAKE_RESERVATION_SOURCE, active: false };
}
// HTML-comment fence markers — verbatim per spec.
export const TAKES_FENCE_BEGIN = '<!--- gbrain:takes:begin -->';
export const TAKES_FENCE_END = '<!--- gbrain:takes:end -->';
/**
* Holder grammar (v0.32 — EXP-4). The contract documented on ParsedTake.holder
* lifted to a runtime check.
*
* Valid (canonical):
* `world` | `brain` | `people/<slug>` | `companies/<slug>`
*
* Valid (legacy compat — production brains shipped with bare-slug holders
* before the namespaced JSDoc landed in PR #795):
* `<slug>` (single lowercase segment with no namespace prefix)
*
* Slug character class is sourced from sync.ts:SLUG_SEGMENT_PATTERN — the
* actual grammar `slugifySegment()` produces, NOT a stricter invented one
* (codex review #3 — `companies/acme.io` and `people/foo_bar` are valid;
* the original PR's `[a-z0-9-]+` would have warned on both).
*
* Catches the eval-flagged error modes:
* - `Alice` — uppercase letter (rejected: not in [a-z0-9._-])
* - `people/Alice-Ex` — mixed case in slug (rejected for same reason)
* - `world/alice-ex` — `world` is a literal, no slash variant
* - `users/alice` — only `people/...` and `companies/...` are namespaced
*
* The legacy bare-slug form is reserved for v0.33 promotion to error;
* v0.32 emits warnings only.
*/
import { SLUG_SEGMENT_PATTERN } from './sync.ts';
export const HOLDER_REGEX = new RegExp(
`^(?:world|brain|(?:people|companies)/${SLUG_SEGMENT_PATTERN.source}|${SLUG_SEGMENT_PATTERN.source})$`,
'u', // required by SLUG_SEGMENT_PATTERN's \p{...} classes (#3417)
);
/**
* Returns true when `holder` matches the documented grammar. Used by
* parseTakesFence to surface TAKES_HOLDER_INVALID warnings in v0.32 (warning
* only — markdown source-of-truth contract preserves the row). Promoted to
* error in v0.33 once production sync-failures show warning rate trending
* to zero.
*/
export function isValidHolder(holder: string): boolean {
return HOLDER_REGEX.test(holder);
}
/** Canonical take kind vocabulary — the fence enum AND the extractor's accepted kinds. */
export const TAKE_KIND_VALUES: ReadonlySet<string> = new Set(['fact', 'take', 'bet', 'hunch']);
const QUALITY_VALUES: ReadonlySet<string> = new Set(['correct', 'incorrect', 'partial', 'unresolvable']);
// v0.30.0: header tokens that mark a v0.30-shape fence. Presence of `quality`
// (or any other resolution column) widens the parser to read 7+ extra cells
// per row. Missing tokens → v0.28 7-column shape, parsed exactly as before.
const RESOLUTION_HEADER_TOKENS = ['resolved', 'quality', 'evidence', 'value', 'unit', 'by'] as const;
type ResolutionColumn = typeof RESOLUTION_HEADER_TOKENS[number];
function parseQualityCell(raw: string): TakeQuality | undefined {
const trimmed = raw.trim().toLowerCase();
if (!trimmed) return undefined;
if (QUALITY_VALUES.has(trimmed)) return trimmed as TakeQuality;
return undefined;
}
function parseFloatCell(raw: string): number | undefined {
const trimmed = raw.trim();
if (!trimmed) return undefined;
const n = parseFloat(trimmed);
return Number.isFinite(n) ? n : undefined;
}
/**
* Normalize a weight for storage. Single source of truth used by both engines
* at all 4 takes write sites (addTakesBatch + updateTake × postgres + pglite).
*
* Pipeline:
* 1. NaN / Infinity / -Infinity → 0.5 (default), clamped=true.
* 2. Out of [0, 1] → clamp to [0, 1], clamped=true.
* 3. Round to 0.05 grid (cross-modal eval over 100K takes flagged 0.74,
* 0.82-style values as false precision; the engine layer enforces a
* coarser grid that matches actual calibration accuracy).
*
* 0 and 1 round to themselves exactly (Math.round(20)/20 = 1.0,
* Math.round(0)/20 = 0). The clamped flag is the trigger for the engine's
* TAKES_WEIGHT_CLAMPED stderr counter; rounding alone does NOT set it.
*
* `undefined` and `null` inputs return 0.5 with clamped=false (the default
* weight when a fence row omits the column).
*/
export function normalizeWeightForStorage(
raw: number | null | undefined,
): { weight: number; clamped: boolean } {
let w = raw ?? 0.5;
let clamped = false;
if (!Number.isFinite(w)) {
clamped = true;
w = 0.5;
} else if (w < 0 || w > 1) {
clamped = true;
w = Math.max(0, Math.min(1, w));
}
return { weight: Math.round(w * 20) / 20, clamped };
}
function parseStringCell(raw: string): string | undefined {
const trimmed = raw.trim();
return trimmed ? trimmed : undefined;
}
// Pipe-row parsing, separator detection, and strikethrough handling moved
// to src/core/fence-shared.ts in v0.32.2 — same primitives are used by
// facts-fence and any future fence-based category. Behavior here is
// byte-identical to the v0.28-shipped inline versions; the takes-fence
// test suite is the regression gate.
import {
parseRowCells,
isSeparatorRow,
stripStrikethrough,
escapeFenceCell as safeFenceCell,
assertFenceRewritable,
} from './fence-shared.ts';
import { indexOfOutsideCode, locateOutsideCode, protectedRegions, unclosedCodeFenceStart } from './fence-scan.ts';
function parseSinceCell(raw: string): { since?: string; until?: string } {
const trimmed = raw.trim();
if (!trimmed) return {};
// Range syntax: `2022-01 → 2026-06` or `2022-01 -> 2026-06`
const rangeMatch = trimmed.match(/^(.+?)\s*(?:→|->)\s*(.+)$/);
if (rangeMatch) {
return { since: rangeMatch[1].trim(), until: rangeMatch[2].trim() };
}
return { since: trimmed };
}
/**
* Slice the body between the fence markers and parse the table.
* Returns empty takes + empty warnings when no fence is present.
*/
export function parseTakesFence(body: string): ParseResult {
const { beginIdx, endIdx } = locateOutsideCode(body, TAKES_FENCE_BEGIN, TAKES_FENCE_END);
const warnings: string[] = [];
if (beginIdx === -1 && endIdx === -1) {
// #3769: the canonical markers use the THREE-dash comment form
// (`<!--- gbrain:takes:begin -->`). A body that mentions the marker text
// without the exact form — most commonly the standard two-dash
// `<!-- gbrain:takes:begin -->` an author or agent writes from memory —
// is a fence the author MEANT to write. Flag it instead of silently
// parsing zero takes.
if (indexOfOutsideCode(body, 'gbrain:takes:begin') !== -1) {
warnings.push(
'TAKES_FENCE_NEAR_MISS: found "gbrain:takes:begin" but not the exact ' +
`marker "${TAKES_FENCE_BEGIN}" — use the three-dash comment form`,
);
}
return { takes: [], warnings, reservedRowNums: [] };
}
if (beginIdx === -1 || endIdx === -1) {
warnings.push('TAKES_FENCE_UNBALANCED: missing begin or end marker');
return { takes: [], warnings, reservedRowNums: [] };
}
if (endIdx < beginIdx) {
warnings.push('TAKES_FENCE_UNBALANCED: end marker before begin');
return { takes: [], warnings, reservedRowNums: [] };
}
const inner = body.slice(beginIdx + TAKES_FENCE_BEGIN.length, endIdx);
const lines = inner.split('\n');
const takes: ParsedTake[] = [];
const reservedRowNums: number[] = [];
let sawHeader = false;
// Map from resolution column name → cell index in the row. Empty when the
// fence is a v0.28 7-column shape; populated when resolution columns appear.
const resolutionColIdx: Partial<Record<ResolutionColumn, number>> = {};
const seenRowNums = new Set<number>();
for (let i = 0; i < lines.length; i++) {
const line = lines[i];
if (!line.trim()) continue;
const cells = parseRowCells(line);
if (!cells) continue;
// Header row: `| # | claim | kind | who | weight | since | source |`
// (v0.28 7-column shape) OR with extra `| resolved | quality | evidence
// | value | unit | by |` columns appended (v0.30 13-column shape).
if (!sawHeader) {
const lower = cells.map(c => c.toLowerCase());
if (lower.includes('claim') && lower.includes('kind')) {
sawHeader = true;
// Detect v0.30 resolution columns. Columns are positional, but tolerate
// any subset (forward-compat: future schemas might add more).
for (const tok of RESOLUTION_HEADER_TOKENS) {
const idx = lower.indexOf(tok);
if (idx !== -1) resolutionColIdx[tok] = idx;
}
continue;
}
// First content row before header — skip with warning.
warnings.push(`TAKES_TABLE_MALFORMED: row before header: "${line.trim()}"`);
continue;
}
// Separator row (just dashes/colons) — skip.
if (isSeparatorRow(cells)) continue;
// Expect 7 cells minimum: row_num, claim, kind, holder, weight, since, source.
if (cells.length < 6) {
warnings.push(`TAKES_TABLE_MALFORMED: only ${cells.length} cells in row "${line.trim()}"`);
continue;
}
const [rowNumStr, claimRaw, kindRaw, holderRaw, weightRaw, sinceRaw, sourceRaw = ''] = cells;
const rowNum = parseInt(rowNumStr, 10);
if (!Number.isFinite(rowNum) || rowNum <= 0) {
warnings.push(`TAKES_TABLE_MALFORMED: invalid row_num "${rowNumStr}"`);
continue;
}
if (seenRowNums.has(rowNum)) {
warnings.push(`TAKES_ROW_NUM_COLLISION: duplicate row_num ${rowNum}`);
continue;
}
seenRowNums.add(rowNum);
const kind = kindRaw.trim().toLowerCase();
if (!TAKE_KIND_VALUES.has(kind)) {
warnings.push(`TAKES_TABLE_MALFORMED: unknown kind "${kindRaw}" (expected fact|take|bet|hunch)`);
continue;
}
// v0.32 EXP-4: holder grammar check. Warning-only — preserve the row
// (markdown source-of-truth contract). Caller (extract-takes.ts) maps
// these into the failedFiles[] payload so the v0_28_0 migration's
// backfill phase emits sync-failures records and doctor's sync_failures
// check shows the breakdown by code (`TAKES_HOLDER_INVALID=N`).
const holderTrimmed = holderRaw.trim();
if (!isValidHolder(holderTrimmed)) {
warnings.push(
`TAKES_HOLDER_INVALID: "${holderTrimmed}" in row ${rowNumStr} (expected: world | brain | people/<slug> | companies/<slug>)`,
);
// Fall through — row is still parsed and stored.
}
const weight = parseFloat(weightRaw);
if (!Number.isFinite(weight)) {
warnings.push(`TAKES_TABLE_MALFORMED: non-numeric weight "${weightRaw}"`);
continue;
}
const { text: claimText, struck } = stripStrikethrough(claimRaw);
if (struck && claimText === TAKE_RESERVATION_CLAIM && sourceRaw.trim() === TAKE_RESERVATION_SOURCE) {
reservedRowNums.push(rowNum);
continue;
}
const { since, until } = parseSinceCell(sinceRaw);
// v0.30 resolution columns. Only populated when the header contained the
// matching tokens AND the row has cells at those positions.
const cellAt = (col: ResolutionColumn): string | undefined => {
const idx = resolutionColIdx[col];
if (idx === undefined) return undefined;
return idx < cells.length ? cells[idx] : undefined;
};
const resolvedAt = cellAt('resolved');
const qualityRaw = cellAt('quality');
const evidenceRaw = cellAt('evidence');
const valueRaw = cellAt('value');
const unitRaw = cellAt('unit');
const byRaw = cellAt('by');
const resolvedQuality = qualityRaw !== undefined ? parseQualityCell(qualityRaw) : undefined;
// Derive resolvedOutcome from quality so the parsed shape is self-consistent
// for callers that read either field.
const resolvedOutcome = resolvedQuality === 'correct' ? true
: resolvedQuality === 'incorrect' ? false
: undefined;
takes.push({
rowNum,
claim: claimText,
kind: kind as string,
holder: holderRaw.trim(),
weight,
sinceDate: since,
untilDate: until,
source: sourceRaw.trim() || undefined,
active: !struck,
resolvedAt: resolvedAt ? parseStringCell(resolvedAt) : undefined,
resolvedQuality,
resolvedOutcome,
resolvedEvidence: evidenceRaw ? parseStringCell(evidenceRaw) : undefined,
resolvedValue: valueRaw ? parseFloatCell(valueRaw) : undefined,
resolvedUnit: unitRaw ? parseStringCell(unitRaw) : undefined,
resolvedBy: byRaw ? parseStringCell(byRaw) : undefined,
});
}
if (!sawHeader && takes.length === 0 && lines.some(l => l.trim().startsWith('|'))) {
warnings.push('TAKES_TABLE_MALFORMED: pipe-rows present but no recognizable header');
}
return { takes, warnings, reservedRowNums };
}
/**
* Render a takes array back to a fenced markdown table. Round-trip safe
* with parseTakesFence. Output uses tight column padding (one space per
* side) — readable but not pretty-printed.
*
* v0.30.0 (Slice A1, codex F3 fix): conditional render of resolution
* columns. When ANY take in the array has `resolvedQuality !== undefined`,
* the renderer widens the table to 13 columns (`# | claim | kind | who |
* weight | since | source | resolved | quality | evidence | value | unit |
* by |`). Pages with no resolved rows keep the narrow 7-column shape
* exactly as v0.28 emitted. The parser tolerates both shapes.
*
* Round-trip preservation is the safety net for the silent-data-loss bug
* codex caught: every CLI that re-renders a fence (cmdUpdate, cmdSupersede,
* cmdAdd) must read existing rows via parseTakesFence and pass them
* through to renderTakesFence so resolution data on resolved rows survives
* unrelated edits to other rows on the same page. The
* round-trip-preservation test in test/takes-fence.test.ts is the
* regression gate.
*/
export function renderTakesFence(takes: ParsedTake[], reservedRowNums: readonly number[] = []): string {
const hasAnyResolution = takes.some(t => t.resolvedQuality !== undefined);
const header = hasAnyResolution
? `| # | claim | kind | who | weight | since | source | resolved | quality | evidence | value | unit | by |`
: `| # | claim | kind | who | weight | since | source |`;
const separator = hasAnyResolution
? `|---|-------|------|-----|--------|-------|--------|----------|---------|----------|-------|------|----|`
: `|---|-------|------|-----|--------|-------|--------|`;
// Reservation rows sit at their row number among the takes (W9F item 4).
const live = new Set(takes.map(t => t.rowNum));
const reserved = [...new Set(reservedRowNums)].filter(n => !live.has(n)).sort((a, b) => a - b);
const ordered: ParsedTake[] = [];
for (const t of takes) {
while (reserved.length && reserved[0]! < t.rowNum) ordered.push(reservationRow(reserved.shift()!));
ordered.push(t);
}
ordered.push(...reserved.map(reservationRow));
const rows = ordered.map(t => {
const claimCell = t.active ? t.claim : `~~${t.claim}~~`;
const sinceCell = t.untilDate ? `${t.sinceDate ?? ''} → ${t.untilDate}` : (t.sinceDate ?? '');
const w = formatWeight(t.weight);
const source = t.source ?? '';
// Escape any pipes inside cells so the table doesn't break. The
// escapeFenceCell primitive lives in fence-shared.ts and is re-aliased
// as `safe` here purely to keep the row-render lines visually compact.
const safe = safeFenceCell;
const baseCells = `| ${t.rowNum} | ${safe(claimCell)} | ${t.kind} | ${safe(t.holder)} | ${w} | ${safe(sinceCell)} | ${safe(source)} |`;
if (!hasAnyResolution) return baseCells;
// Resolution cells. Empty string for unresolved rows keeps the table
// visually clean; the parser treats empty cells as undefined fields.
const resolved = t.resolvedAt ? safe(t.resolvedAt) : '';
const quality = t.resolvedQuality ?? '';
const evidence = t.resolvedEvidence ? safe(t.resolvedEvidence) : '';
// F3: resolvedValue is an UNBOUNDED measured value (usd/count/pct), NOT a
// weight on the 0..1 grid. formatWeight's 2-decimal round would diverge md
// from the DB (12345.678 → 12345.68). Render it full-precision. Only the
// weight cell (`w` above) stays on formatWeight; `value` is the sole
// numeric resolution cell.
const value = t.resolvedValue !== undefined ? String(t.resolvedValue) : '';
const unit = t.resolvedUnit ? safe(t.resolvedUnit) : '';
const by = t.resolvedBy ? safe(t.resolvedBy) : '';
return `${baseCells} ${resolved} | ${quality} | ${evidence} | ${value} | ${unit} | ${by} |`;
});
// #4615: the leading double-'' emits a BLANK LINE between the begin marker
// and the header — GFM parsers (Obsidian 1.3.2+, GitHub, VS Code) need it
// to render the fence as a table (same fix as renderFactsTable). The
// parser skips blank lines, so this is round-trip safe.
const inner = ['', '', header, separator, ...rows, ''].join('\n');
return `${TAKES_FENCE_BEGIN}${inner}${TAKES_FENCE_END}`;
}
function formatWeight(w: number): string {
// Match common spec form: 1.0, 0.85, 0.7. Strip trailing zeros except one.
if (Number.isInteger(w)) return w.toFixed(1);
return String(parseFloat(w.toFixed(2)));
}
/**
* The page's next take row number from its own text: GBRA-54's
* `nextFreeRowNum`, the one allocator. Loaded lazily because the fence-repair
* modules import this one.
*/
function nextTakeRowNum(body: string): number {
const { nextFreeRowNum } = require('./fence-repair/normalize.ts') as typeof import('./fence-repair/normalize.ts');
return nextFreeRowNum({ compiled_truth: body, timeline: '' });
}
/**
* Append a new take row to the body. If a fenced takes table exists, the
* row is added to the end of it. If not, a new `## Takes` section + fence
* is created at the end of the body.
*
* Append-only per CEO-D6 + eng-D9: row_num is `newRow.rowNum` when given
* (callers with stored rows pass `nextFreeRowNum` over them), else
* `nextFreeRowNum` over the body. Never a number used on the page before,
* reservation rows included (W9F item 4).
*
* `claim`, `kind`, `holder` of the input are required; `weight` defaults
* to 0.5 if omitted; `active` defaults to true. Throws `FenceRewriteRefusal`
* when the existing fence does not parse cleanly (any warning), since the
* rewrite would drop the rows the parser skipped.
*/
export function upsertTakeRow(
body: string,
newRow: Omit<ParsedTake, 'rowNum'> & { rowNum?: number },
): { body: string; rowNum: number } {
const parsed = parseTakesFence(body);
// Re-rendering a fence the parser skipped rows of would delete them.
assertFenceRewritable('takes', parsed);
const { takes, reservedRowNums } = parsed;
const nextRowNum = newRow.rowNum ?? nextTakeRowNum(body);
const allRows: ParsedTake[] = [
...takes,
{
rowNum: nextRowNum,
claim: newRow.claim,
kind: newRow.kind,
holder: newRow.holder,
weight: newRow.weight ?? 0.5,
sinceDate: newRow.sinceDate,
untilDate: newRow.untilDate,
source: newRow.source,
active: newRow.active ?? true,
},
];
const newFence = renderTakesFence(allRows, reservedRowNums);
// If fence already exists, replace it. Otherwise append a Takes section.
const { beginIdx, endIdx } = locateOutsideCode(body, TAKES_FENCE_BEGIN, TAKES_FENCE_END);
let out: string;
if (beginIdx !== -1 && endIdx !== -1) {
out = body.slice(0, beginIdx) + newFence + body.slice(endIdx + TAKES_FENCE_END.length);
} else {
// No fence yet — append a fresh Takes section at the end, or above an
// unclosed code block that runs to EOF (it would render the fence as code).
const codeAt = unclosedCodeFenceStart(body);
if (codeAt === -1) {
const sep = body.endsWith('\n') ? '\n' : '\n\n';
out = `${body}${sep}## Takes\n\n${newFence}\n`;
} else {
const head = body.slice(0, codeAt);
const sep = head === '' || head.endsWith('\n\n') ? '' : head.endsWith('\n') ? '\n' : '\n\n';
out = `${head}${sep}## Takes\n\n${newFence}\n\n${body.slice(codeAt)}`;
}
}
return { body: out, rowNum: nextRowNum };
}
/**
* Supersede an existing row: strike through the target row's claim AND
* append a new row at the end with the new claim. Both rows preserved
* in markdown for git-blame archaeology. Returns oldRowNum + newRowNum.
* The new row takes `newRowNum` when given, else `nextFreeRowNum` over the
* body (W9F item 4).
*
* Throws when the target row is not found in the fence, and
* `FenceRewriteRefusal` when the fence does not parse cleanly.
*/
export function supersedeRow(
body: string,
oldRowNum: number,
replacement: Omit<ParsedTake, 'rowNum' | 'active'>,
newRowNum: number = nextTakeRowNum(body),
): { body: string; oldRowNum: number; newRowNum: number } {
const parsed = parseTakesFence(body);
assertFenceRewritable('takes', parsed);
const { takes, reservedRowNums } = parsed;
const idx = takes.findIndex(t => t.rowNum === oldRowNum);
if (idx === -1) {
throw new Error(`supersedeRow: row #${oldRowNum} not found in takes fence`);
}
const oldClaim = takes[idx].claim;
// The pointer lives on the OLD row (the canonical projection reads it there),
// after the row's own provenance. A stale self-reference written by older
// versions onto a then-new row is dropped so it cannot shadow the real pointer.
const priorSource = takes[idx].source?.trim() ?? '';
const originalSource = /^superseded by #\d+$/i.test(priorSource) ? '' : priorSource;
const updatedTakes: ParsedTake[] = takes.map((t, i) =>
i === idx
? { ...t, active: false, source: originalSource ? `${originalSource}; superseded by #${newRowNum}` : `superseded by #${newRowNum}` }
: t,
);
updatedTakes.push({
rowNum: newRowNum,
claim: replacement.claim,
kind: replacement.kind,
holder: replacement.holder,
weight: replacement.weight,
sinceDate: replacement.sinceDate,
untilDate: replacement.untilDate,
source: replacement.source ?? '',
active: true,
});
void oldClaim; // Reserved for future "show what changed" diff helper.
const newFence = renderTakesFence(updatedTakes, reservedRowNums);
const { beginIdx, endIdx } = locateOutsideCode(body, TAKES_FENCE_BEGIN, TAKES_FENCE_END);
if (beginIdx === -1 || endIdx === -1) {
throw new Error('supersedeRow: fence markers missing in body (unexpected — parseTakesFence found rows)');
}
const out = body.slice(0, beginIdx) + newFence + body.slice(endIdx + TAKES_FENCE_END.length);
return { body: out, oldRowNum, newRowNum };
}
/**
* Strip the fenced takes block from the body. Used by the chunker so takes
* content lives ONLY in the takes table, not duplicated in page chunks
* (Codex P0 #3 privacy fix). When no fence is present, returns body
* unchanged. An unpaired begin marker strips everything after it, like
* sanitizeRemoteBody.
*/
export function stripTakesFence(body: string): string {
// Pages without a compiled body (e.g. metadata-only rows from a read op)
// have nothing to strip. Guard so the privacy strip is a safe no-op rather
// than crashing on `undefined.indexOf`.
if (typeof body !== 'string') return body;
// Privacy boundary: the same regions sanitizeRemoteBody hides, including a
// fence quoted in a code block and an ambiguous tail (see protectedRegions).
const { regions, truncatedAt } = protectedRegions(body, TAKES_PAIR);
if (regions.length === 0 && truncatedAt === -1) return body;
let out = '';
let cursor = 0;
for (const region of regions) {
out += body.slice(cursor, region.start);
cursor = region.end;
}
return out + (truncatedAt === -1 ? body.slice(cursor) : body.slice(cursor, truncatedAt));
}
const TAKES_PAIR = [{ begin: TAKES_FENCE_BEGIN, end: TAKES_FENCE_END }];