Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
43.7 KB
Raw Blame
/**
 * Shared takes write-through core — consumed by the `gbrain takes` CLI
 * (src/commands/takes.ts) and the takes_* MCP ops (src/core/ops/takes.ts).
 *
 * MARKDOWN IS CANONICAL (the extract-takes contract, src/core/cycle/
 * extract-takes.ts): the md→DB reconcile upserts ON CONFLICT(page_id,row_num)
 * and the extract rebuild lane deletes+reinserts from md, so any writer that
 * creates DB-only rows gets silently clobbered by the next sync/extract. Every
 * mutation here is therefore md-FIRST — row numbers derive from the fence
 * (takes-fence.ts), the .md file is written before the DB — and the markdown
 * write is REQUIRED: when the page file can't be located the write REFUSES
 * (TakesWriteError 'mirror_unavailable') instead of creating divergence.
 *
 * Every mutate runs this pipeline:
 *
 *   lock(slug, timeout) ─▶ page id (DB, source-scoped) ─▶ read .md
 *        │                                                   │
 *        │                    row lookup + holder fence ◀────┘ (fence rows,
 *        │                          │                          md-canonical)
 *        │                    fence edit ─▶ write .md ─▶ DB mirror ─▶ release
 *        ▼
 *   [contended → 'page_locked' (retryable)]
 *
 * The DB mirror for add/update/supersede is addTakesBatch's upsert of the
 * affected fence rows — the same primitive the extract pipeline uses, so the
 * mirror can never disagree with a later reconcile. Its DO UPDATE clause
 * touches base columns only (resolution columns preserved). resolve mirrors
 * via engine.resolveTake (resolution fields aren't in TakeBatchInput);
 * a drifted DB missing the row is self-healed by upserting the base row
 * first — md is the truth being propagated.
 *
 * Holder fence (remote callers): callers pass `allowList` (null/undefined =
 * trusted local, unfenced; [] = deny-all). Row-level checks look up the
 * PARSED FENCE row and a fenced holder presents as 'row_not_found' — the
 * same shape as a genuinely missing row — hiding content and holder.
 * (Existence-by-count via dense row numbers is a documented, accepted
 * limitation — see ops/takes.ts.)
 */

import { readFileSync, existsSync, mkdirSync } from 'node:fs';
import { dirname, join } from 'node:path';
import type { BrainEngine, TakeBatchInput, TakeKind } from './engine.ts';
import {
  parseTakesFence,
  renderTakesFence,
  upsertTakeRow,
  supersedeRow,
  TAKES_FENCE_BEGIN,
  TAKES_FENCE_END,
  type ParsedTake,
  type ParseResult,
  type TakeQuality,
} from './takes-fence.ts';
import { locateOutsideCode } from './fence-scan.ts';
import { withPageLock } from './page-lock.ts';
import { resolvePageFilePath, resolveSourceLocalFilePath } from './markdown.ts';
import { sanitizeRecordedSourcePath, recordedPathFromFileUri, scannerSlugRootMode } from './write-through.ts';
import { isWriteTargetContained, msysToNativePath } from './path-confine.ts';
import { atomicWriteFileSync } from './atomic-write.ts';
import { commitWriteThroughFile, isDurabilityHardened } from './brain-repo-durability.ts';
import { maintenanceTransaction } from './persistence/attribution.ts';
import type { WriteTrust } from './trust/tier.ts';

export type TakesWriteErrorCode =
  | 'page_not_found'      // slug has no pages row (scoped)
  | 'row_not_found'       // fence lacks the row OR the holder fence masks it
  | 'already_resolved'    // resolved rows are immutable; supersede instead
  | 'row_inactive'        // superseded rows can't be updated/resolved again
  | 'holder_denied'       // add with a holder outside the allow-list
  | 'no_fields'           // update with zero mutable fields
  | 'mirror_unavailable'  // sync.repo_path unset, page file absent, or write target escapes the source root
  | 'page_locked'         // lock contention within the timeout (retryable)
  | 'fence_unparsed'      // the page's fence has parser-skipped rows a whole-fence re-render would delete
  | 'invalid_input';      // free-text field carries control chars, fence markers, or out-of-range values

export class TakesWriteError extends Error {
  code: TakesWriteErrorCode;
  hint?: string;
  constructor(code: TakesWriteErrorCode, message: string, hint?: string) {
    super(message);
    this.name = 'TakesWriteError';
    this.code = code;
    this.hint = hint;
  }
}

/** null/undefined = trusted local (unfenced); [] = deny-all. */
export type HolderAllowList = readonly string[] | null | undefined;

export interface TakesWriteTarget {
  engine: BrainEngine;
  slug: string;
  /** Brain repo dir (resolveTakesRepoDir or an explicit CLI --dir). */
  brainDir: string;
  /** Scalar source scope for the pages lookup (writes are scalar). */
  sourceId?: string;
  allowList?: HolderAllowList;
  /** Lock wait budget. CLI keeps the 30s default; ops pass ~2000. */
  lockTimeoutMs?: number;
  /** #5575 I2: a deriver's tier for the added row (`think --take`); absent, the row is undeclared. */
  trust?: WriteTrust;
}

/**
 * The markdown write always succeeds before the DB mirror is attempted, and md
 * is canonical — so a failed DB mirror is NOT fatal (the next reconcile heals
 * it; throwing would make the caller retry and duplicate the durable md row).
 * `mirror_warning` carries the DB-mirror error when it happened; `written` is
 * still true because the markdown row is on disk.
 */
export interface TakeMirror { written: true; path: string; mirror_warning?: string }

/** DB-mirror failures are non-fatal (md is canonical) — stringify for the warning. */
function mirrorErrorMessage(err: unknown): string {
  return err instanceof Error ? err.message : String(err);
}

/**
 * Resolve the markdown brain dir for takes write-through. Returns null when
 * `sync.repo_path` is unset or missing on disk — callers decide the refusal
 * shape (ops: 'mirror_unavailable'; CLI: its historical error text + exit 1).
 */
export async function resolveTakesRepoDir(engine: BrainEngine): Promise<string | null> {
  const configured = await engine.getConfig('sync.repo_path');
  if (configured && existsSync(configured)) return configured;
  return null;
}

/**
 * P1-1 (source isolation): resolve the ACTUAL per-source markdown path for a
 * write, mirroring write-through.ts's topology so a source-scoped take lands in
 * the SAME working tree `gbrain sync` reads it back from. The old
 * `join(brainDir, slug.md)` ignored the page's source entirely, so a non-default
 * source's write clobbered a same-slug file in the wrong tree.
 *
 *   1. Source has its OWN `local_path` working tree → use the page's recorded
 *      `source_path`, removing a duplicated Git-root scope when local_path is
 *      a repo subdirectory; a DB-born page falls back to `<local_path>/<slug>.md`.
 *   2. No per-source `local_path` → the shared host repo (`brainDir`): default
 *      source at the root, non-default nested under `.sources/<id>/`.
 *
 * #3605: in BOTH topologies the page's vetted recorded path (`source_path`,
 * or a contained `file://` `source_uri` from `gbrain capture --file`) is
 * preferred over a slug-derived name — the on-disk name is often NOT the slug
 * (`people/Jane Doe.md` has slug `people/jane-doe`), so deriving `<slug>.md`
 * minted a stray twin on add and refused update/resolve with
 * 'mirror_unavailable' even though the page's file was right there. A hostile
 * or unusable recorded path sanitizes to null and falls back to the slug path.
 *
 * The returned `writeRoot` is the containment boundary enforced before any write
 * (P1-2). `resolvePageFilePath` does the slug→path join for the fallback case.
 */
async function resolveTakesFilePath(
  engine: BrainEngine,
  brainDir: string | null,
  slug: string,
  sourceId?: string,
): Promise<{ path: string; writeRoot: string }> {
  const src = sourceId ?? 'default';
  const rows = await engine.executeRaw<
    { local_path: string | null; source_path: string | null; source_uri: string | null }
  >(
    `SELECT s.local_path, p.source_path, p.source_uri
       FROM sources s
       LEFT JOIN pages p ON p.source_id = s.id AND p.slug = $2 AND p.deleted_at IS NULL
      WHERE s.id = $1
      LIMIT 1`,
    [src, slug],
  );
  // #2955: heal Git Bash/MSYS-recorded local_path (`/c/Users/x`) before any
  // join/containment math — same normalization as write-through.ts. Without
  // it the writeRoot resolves to a phantom `<cwd-drive>:\c\...` on Windows.
  const sourceLocalPath = rows[0]?.local_path ? msysToNativePath(rows[0].local_path) : null;
  const recordedSourcePath = rows[0]?.source_path ?? null;
  const recordedUri = rows[0]?.source_uri ?? null;
  if (sourceLocalPath) {
    const recordedPath =
      (recordedSourcePath ? resolveSourceLocalFilePath(sourceLocalPath, recordedSourcePath, slug, await scannerSlugRootMode(engine, src, sourceLocalPath)) : null) ??
      (() => {
        const fromUri = recordedPathFromFileUri(recordedUri, sourceLocalPath);
        return fromUri ? join(sourceLocalPath, fromUri) : null;
      })();
    // A null recorded path means a DB-born page. Keep the established slug path.
    const path = recordedPath ?? resolvePageFilePath(sourceLocalPath, slug, 'default');
    return { path, writeRoot: sourceLocalPath };
  }
  // #4473: a null brainDir (sync.repo_path unset) is only survivable when the
  // source carries its own local_path (handled above). A host-repo page has
  // nowhere to land — refuse with the standard mirror_unavailable shape so
  // batch callers (takes bootstrap) can skip-and-count instead of aborting.
  if (brainDir === null) {
    throw new TakesWriteError(
      'mirror_unavailable',
      `No markdown repo for source '${src}' — sync.repo_path is unset and the source has no local_path.`,
      'takes_mirror_unavailable',
    );
  }
  const pageRoot = src === 'default' ? brainDir : join(brainDir, '.sources', src);
  const knownPath =
    sanitizeRecordedSourcePath(recordedSourcePath) ??
    recordedPathFromFileUri(recordedUri, pageRoot);
  const path = knownPath
    ? join(pageRoot, knownPath)
    : resolvePageFilePath(brainDir, slug, src);
  return { path, writeRoot: brainDir };
}

/** Test seam: pins the #2955 msys local_path healing at THIS read site. */
export const __takesWriteTesting = { resolveTakesFilePath };

/**
 * #4473 — public read-only probe of the takes write path. The takes-bootstrap
 * sweep (extract-takes-from-pages.ts) checks file existence BEFORE spending an
 * LLM call on a page it could never write (a skipped page is rescanned by
 * every future run, so classifying it first would re-burn budget each time).
 * Throws 'mirror_unavailable' when the page has no resolvable markdown home.
 */
export async function resolveTakesWritePath(
  engine: BrainEngine,
  brainDir: string | null,
  slug: string,
  sourceId?: string,
): Promise<{ path: string; writeRoot: string }> {
  return resolveTakesFilePath(engine, brainDir, slug, sourceId);
}

async function getPageId(engine: BrainEngine, slug: string, sourceId?: string): Promise<number> {
  const rows = sourceId
    ? await engine.executeRaw<{ id: number }>(
        `SELECT id FROM pages WHERE slug = $1 AND source_id = $2 LIMIT 1`,
        [slug, sourceId],
      )
    : await engine.executeRaw<{ id: number }>(
        `SELECT id FROM pages WHERE slug = $1 LIMIT 1`,
        [slug],
      );
  if (!rows[0]) {
    throw new TakesWriteError(
      'page_not_found',
      `Page not found in brain: ${slug}${sourceId ? ` (source=${sourceId})` : ''}.`,
      'Run a brain sync first, or check the slug/source.',
    );
  }
  return rows[0].id;
}

function assertHolderAllowed(holder: string, allowList: HolderAllowList): void {
  if (allowList === null || allowList === undefined) return; // trusted local
  if (!allowList.includes(holder)) {
    throw new TakesWriteError(
      'holder_denied',
      `holder '${holder}' is not in this caller's takes-holder allow-list.`,
      'holder_not_in_allowlist',
    );
  }
}

/**
 * Fence-injection guard for free-text cells. Every user-supplied string that
 * lands in a fence cell must be single-line (control chars — newlines
 * included — would let one cell mint extra table rows) and must not carry the
 * fence-marker text: 'gbrain:takes' is the tightest common substring of
 * TAKES_FENCE_BEGIN/TAKES_FENCE_END, so a cell containing it could terminate
 * the fence early or open a second one, rewriting rows the caller doesn't own.
 */
const CELL_CONTROL_CHARS = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f\n\r\t]/;
const FENCE_MARKER_SUBSTRING = 'gbrain:takes';
function assertSafeCellText(field: string, value: string | undefined): void {
  if (typeof value !== 'string') return;
  if (CELL_CONTROL_CHARS.test(value)) {
    throw new TakesWriteError(
      'invalid_input',
      `${field} contains control characters (newlines included) — takes fence cells are single-line.`,
    );
  }
  if (value.includes(FENCE_MARKER_SUBSTRING)) {
    throw new TakesWriteError(
      'invalid_input',
      `${field} contains the takes fence marker text ('${FENCE_MARKER_SUBSTRING}') — refusing a fence-injection write.`,
    );
  }
  // F2: a wholly-strikethrough value (`~~x~~`) round-trips as active:false —
  // fence-shared.ts stripStrikethrough matches ^~~(.+?)~~$ — so writing it as an
  // active claim would silently mark the take inactive on the next parse.
  if (/^~~[\s\S]*~~$/.test(value.trim())) {
    throw new TakesWriteError(
      'invalid_input',
      `${field} is wholly strikethrough-wrapped; that markup marks a take inactive on the next parse.`,
    );
  }
}

/**
 * #4473 — non-throwing form of the fence-cell guards. The takes-bootstrap
 * sweep pre-filters LLM-authored claims with this so one hostile/garbled
 * claim drops alone instead of sinking the page's other claims (the writer
 * below still asserts — defense in depth).
 */
export function isSafeFenceCellText(value: string): boolean {
  try {
    assertSafeCellText('cell', value);
    return true;
  } catch {
    return false;
  }
}

/**
 * The param docs promise weight 0..1 and the DB clamps out-of-range values
 * (normalizeWeightForStorage) — writing the raw value to md would diverge the
 * markdown from the DB mirror, so out-of-range is refused up front.
 */
function assertValidWeight(weight: number | undefined): void {
  if (weight === undefined) return;
  if (!Number.isFinite(weight) || weight < 0 || weight > 1) {
    throw new TakesWriteError('invalid_input', `weight must be a number in [0, 1] (got ${weight}).`);
  }
}

const SINCE_DATE_RE = /^\d{4}-\d{2}(-\d{2})?$/;
function assertValidSinceDate(value: string | undefined): void {
  if (value === undefined) return;
  if (!SINCE_DATE_RE.test(value)) {
    throw new TakesWriteError(
      'invalid_input',
      `since date must be 'YYYY-MM' or 'YYYY-MM-DD' (got '${value}').`,
    );
  }
}

/**
 * Row lookup with the no-existence-leak masking: a row that is absent from
 * the fence AND a row whose holder the caller cannot see produce the SAME
 * error shape.
 */
function findFenceRow(takes: ParsedTake[], rowNum: number, allowList: HolderAllowList, slug: string): ParsedTake {
  const target = takes.find(t => t.rowNum === rowNum);
  const visible = target
    && (allowList === null || allowList === undefined || allowList.includes(target.holder));
  if (!target || !visible) {
    throw new TakesWriteError('row_not_found', `Row #${rowNum} not found on ${slug}.`);
  }
  return target;
}

function readPageBody(path: string): string {
  if (!existsSync(path)) {
    throw new TakesWriteError(
      'mirror_unavailable',
      `Page file not found at ${path} — takes are markdown-canonical, so the write is refused.`,
      'takes_mirror_unavailable',
    );
  }
  return readFileSync(path, 'utf-8');
}

/**
 * P1-2: contain the target within the source's working tree before any
 * mkdir/write (a pre-existing hostile row or a symlinked intermediate dir must
 * not escape), then atomic temp+rename so a reader never observes a torn file
 * and a crash mid-write leaves only a tmp sibling.
 */
function writePageBody(path: string, body: string, writeRoot: string, slug: string): void {
  if (!isWriteTargetContained(path, writeRoot)) {
    throw new TakesWriteError(
      'mirror_unavailable',
      'takes write target escapes the source root',
      'path_escapes_source_root',
    );
  }
  mkdirSync(dirname(path), { recursive: true });
  atomicWriteFileSync(path, body);
  // Same #2426 contract as put_page write-through: a durability-hardened repo
  // gets a best-effort, path-limited commit; a failed commit never fails the write.
  if (isDurabilityHardened(writeRoot)) commitWriteThroughFile(writeRoot, path, slug);
}

/**
 * F1 (cross-holder data-loss guard): the row-targeting mutates re-render the
 * WHOLE fence from `parsed.takes`, so any row parseTakesFence skipped (duplicate
 * row_num, unknown kind outside {fact,take,bet,hunch}, malformed cells) — or any
 * row it flagged — would be permanently deleted on the next write, INCLUDING a
 * row held by an identity a world-fenced caller can't see. Refuse the write when
 * the fence carries any parse warning; it must be reconciled first.
 */
function assertFenceRoundTrips(parsed: ParseResult): void {
  if (parsed.warnings.length > 0) {
    throw new TakesWriteError(
      'fence_unparsed',
      `The page's takes fence has rows this version can't safely round-trip: ${parsed.warnings[0]}`,
      // #3697: this used to name `gbrain extract takes --slugs`, which is not the
      // command grammar (extract has links/timeline/all; takes extraction lives
      // under `gbrain takes extract`). Point at surfaces that exist.
      "Reconcile the page's takes fence before mutating — it contains rows this version can't safely round-trip. Preview its repair with `gbrain repair fences` (read-only; it names the exact edit when gbrain will not repair it), fix the malformed fence rows by hand, or re-extract via `gbrain takes extract --from-pages --include-covered`.",
    );
  }
}

/**
 * Re-render the body's takes fence with `rows`. The fence's reservation rows
 * stay, and `reserve` adds new ones (W9F item 4: `takes remove`).
 */
function replaceFence(body: string, rows: ParsedTake[], reserve: readonly number[] = []): string {
  const newFence = renderTakesFence(rows, [...parseTakesFence(body).reservedRowNums, ...reserve]);
  const { beginIdx, endIdx } = locateOutsideCode(body, TAKES_FENCE_BEGIN, TAKES_FENCE_END);
  return body.slice(0, beginIdx) + newFence + body.slice(endIdx + TAKES_FENCE_END.length);
}

function toBatchInput(pageId: number, t: ParsedTake, supersededBy?: number | null): TakeBatchInput {
  return {
    page_id: pageId,
    row_num: t.rowNum,
    claim: t.claim,
    kind: t.kind,
    holder: t.holder,
    weight: t.weight,
    since_date: t.sinceDate,
    until_date: t.untilDate,
    source: t.source,
    active: t.active,
    superseded_by: supersededBy ?? null,
  };
}

/** The row a canonical takes fence projects: an inactive row citing `superseded by #N` points at row N. */
function toCanonicalBatchInput(pageId: number, t: ParsedTake): TakeBatchInput {
  return toBatchInput(pageId, t, t.active ? null : Number(t.source?.match(/superseded by #(\d+)/)?.[1]) || null);
}

async function withTakesLock<T>(
  target: Pick<TakesWriteTarget, 'slug' | 'lockTimeoutMs'>,
  fn: () => Promise<T>,
): Promise<T> {
  try {
    return await withPageLock(target.slug, fn, {
      ...(target.lockTimeoutMs !== undefined ? { timeoutMs: target.lockTimeoutMs } : {}),
    });
  } catch (err) {
    if (err instanceof TakesWriteError) throw err;
    if (err instanceof Error && err.message.includes('could not acquire lock')) {
      throw new TakesWriteError(
        'page_locked',
        `Another writer holds the page lock for ${target.slug} — retry shortly.`,
        'retryable',
      );
    }
    throw err;
  }
}

export interface AddTakeInput {
  claim: string;
  kind: TakeKind;
  holder: string;
  weight?: number;
  source?: string;
  sinceDate?: string;
}

/**
 * Carry take resolutions recorded only in the database into the page's takes
 * fence, so a republication of the page keeps them: the canonical projection
 * writes every resolution column from the fence. A resolution the fence
 * cannot carry losslessly (no quality, a multi-line or fence-breaking cell)
 * and a fence with rows the parser skipped refuse with a TakesWriteError
 * instead of publishing a body that would clear or drop data.
 */
export async function materializeTakeResolutions(engine: BrainEngine, pageId: number, body: string): Promise<string> {
  const parsed = parseTakesFence(body);
  const rows = parsed.takes.length ? await engine.executeRaw<{ row_num: number; resolved_at: Date | string; resolved_quality: TakeQuality | null;
    resolved_source: string | null; resolved_value: number | string | null; resolved_unit: string | null; resolved_by: string | null }>(
    `SELECT row_num,resolved_at,resolved_quality,resolved_source,resolved_value,resolved_unit,resolved_by FROM takes
      WHERE page_id=$1 AND resolved_at IS NOT NULL`, [pageId]) : [];
  const missing = new Map(rows.filter(row => parsed.takes.some(take => take.rowNum === Number(row.row_num)
    && take.resolvedAt === undefined && take.resolvedQuality === undefined)).map(row => [Number(row.row_num), row]));
  if (!missing.size) return body;
  assertFenceRoundTrips(parsed);
  const takes = parsed.takes.map(take => {
    const row = missing.get(take.rowNum);
    if (!row) return take;
    if (!row.resolved_quality) {
      throw new TakesWriteError('invalid_input', `Take row #${take.rowNum} has a resolution without a quality, which the takes fence cannot carry; republishing would clear it.`);
    }
    for (const [field, value] of [['resolved_source', row.resolved_source], ['resolved_unit', row.resolved_unit], ['resolved_by', row.resolved_by]] as const) {
      assertSafeCellText(field, value ?? undefined);
    }
    return { ...take, resolvedAt: new Date(row.resolved_at).toISOString(), resolvedQuality: row.resolved_quality,
      resolvedEvidence: row.resolved_source ?? undefined, resolvedValue: row.resolved_value === null ? undefined : Number(row.resolved_value),
      resolvedUnit: row.resolved_unit ?? undefined, resolvedBy: row.resolved_by ?? undefined };
  });
  const next = replaceFence(body, takes);
  const reparsed = parseTakesFence(next);
  assertFenceRoundTrips(reparsed);
  if (reparsed.takes.length !== takes.length) throw new TakesWriteError('invalid_input', 'The takes fence lost rows while carrying database resolutions.');
  for (const take of takes) {
    if (!missing.has(take.rowNum)) continue;
    const back = reparsed.takes.find(t => t.rowNum === take.rowNum);
    if (!back || back.resolvedQuality !== take.resolvedQuality || (back.resolvedEvidence ?? undefined) !== take.resolvedEvidence
      || back.resolvedValue !== take.resolvedValue || (back.resolvedUnit ?? undefined) !== take.resolvedUnit || (back.resolvedBy ?? undefined) !== take.resolvedBy) {
      throw new TakesWriteError('invalid_input', `Take row #${take.rowNum}'s database resolution does not round-trip through the takes fence.`);
    }
  }
  return next;
}

/**
 * Every stored take of page `pageId` as its fence row, in row order, resolution cells included. A rewrite that dropped
 * the page's takes fence leaves exactly these rows stored (held `fence_absent` on a managed brain, kept by the takes
 * reconcile on an unmanaged one); a take the user removed, or an empty fence retired, is no longer among them. A stored
 * resolution with no quality, which the fence cannot carry, refuses (`invalid_input`) instead of being dropped.
 */
async function storedTakeRows(engine: BrainEngine, pageId: number): Promise<ParsedTake[]> {
  const rows = await engine.executeRaw<{ row_num: number; claim: string; kind: TakeKind; holder: string; weight: number; since_date: string | null; until_date: string | null;
    source: string | null; active: boolean; resolved_at: Date | string | null; resolved_quality: TakeQuality | null; resolved_outcome: boolean | null; resolved_source: string | null;
    resolved_value: number | string | null; resolved_unit: string | null; resolved_by: string | null }>(`SELECT row_num, claim, kind, holder, weight, since_date, until_date, source, active,
      resolved_at, resolved_quality, resolved_outcome, resolved_source, resolved_value, resolved_unit, resolved_by FROM takes WHERE page_id=$1 ORDER BY row_num`, [pageId]);
  return rows.map(t => {
    if (t.resolved_at !== null && !t.resolved_quality) {
      throw new TakesWriteError('invalid_input', `Take row #${t.row_num} has a resolution without a quality, which the takes fence cannot carry; re-creating the takes section would clear it.`);
    }
    return { rowNum: Number(t.row_num), claim: t.claim, kind: t.kind, holder: t.holder, weight: Number(t.weight), active: t.active,
      ...(t.since_date ? { sinceDate: t.since_date } : {}), ...(t.until_date ? { untilDate: t.until_date } : {}), ...(t.source ? { source: t.source } : {}),
      ...(t.resolved_quality ? { resolvedQuality: t.resolved_quality, ...(t.resolved_at ? { resolvedAt: new Date(t.resolved_at).toISOString() } : {}),
        ...(t.resolved_outcome !== null ? { resolvedOutcome: t.resolved_outcome } : {}), ...(t.resolved_source ? { resolvedEvidence: t.resolved_source } : {}),
        ...(t.resolved_value !== null ? { resolvedValue: Number(t.resolved_value) } : {}), ...(t.resolved_unit ? { resolvedUnit: t.resolved_unit } : {}),
        ...(t.resolved_by ? { resolvedBy: t.resolved_by } : {}) } : {}) };
  });
}

/**
 * `body` with the page's stored takes (`storedTakeRows`) rendered into a new takes section when it has no takes fence
 * marker at all, else unchanged. The writers that create the fence (`addTakeToPage`, `appendTakesToPageMdFirst` and
 * the managed `takes extract --from-pages` put) go through this, so their own rows number after the stored ones:
 * otherwise they number from 1, overwrite stored takes in place, and the next projection deletes the rest. A body with
 * a near-miss marker (`<!-- gbrain:takes:begin -->`) refuses `fence_unparsed`, as each writer refuses it without
 * stored takes, and a render that would not read back row for row, every stored cell unchanged, refuses (`invalid_input`)
 * instead of dropping or changing a take.
 */
export async function withStoredTakesFence(engine: BrainEngine, pageId: number, body: string): Promise<string> {
  const { beginIdx, endIdx } = locateOutsideCode(body, TAKES_FENCE_BEGIN, TAKES_FENCE_END);
  if (beginIdx !== -1 || endIdx !== -1) return body;
  const rows = await storedTakeRows(engine, pageId);
  if (!rows.length) return body;
  assertFenceRoundTrips(parseTakesFence(body));
  for (const row of rows) {
    for (const [field, value] of [['claim', row.claim], ['source', row.source], ['resolved_source', row.resolvedEvidence], ['resolved_unit', row.resolvedUnit], ['resolved_by', row.resolvedBy]] as const) {
      assertSafeCellText(field, value);
    }
  }
  const next = replaceFence(upsertTakeRow(body, rows[0]!).body, rows);
  const reparsed = parseTakesFence(next);
  assertFenceRoundTrips(reparsed);
  if (reparsed.takes.length !== rows.length) throw new TakesWriteError('invalid_input', 'The takes fence lost rows while carrying the stored takes of the page.');
  const cell = (value: unknown) => (value === '' || value === null ? undefined : value);
  const fields = ['claim', 'kind', 'holder', 'sinceDate', 'untilDate', 'source', 'active', 'resolvedQuality', 'resolvedEvidence', 'resolvedValue', 'resolvedUnit', 'resolvedBy'] as const;
  const changed = rows.find(row => {
    const back = reparsed.takes.find(take => take.rowNum === row.rowNum);
    return !back || fields.some(field => cell(back[field]) !== cell(row[field]));
  });
  if (changed) throw new TakesWriteError('invalid_input', `Take row #${changed.rowNum} would not read back unchanged from the takes fence, so re-creating the section would change it.`);
  return next;
}

/** Compose the same append sequence used by the legacy md-first writer. */
export function appendTakesToPageBody(body: string, rows: ReadonlyArray<AddTakeInput>): { body: string; rowNums: number[] } {
  for (const row of rows) {
    assertHolderAllowed(row.holder, null);
    assertSafeCellText('claim', row.claim);
    assertSafeCellText('kind', row.kind);
    assertSafeCellText('holder', row.holder);
    assertSafeCellText('source', row.source);
    assertValidWeight(row.weight);
    assertValidSinceDate(row.sinceDate);
  }
  assertFenceRoundTrips(parseTakesFence(body));
  let nextBody = body;
  const rowNums: number[] = [];
  for (const row of rows) {
    const result = upsertTakeRow(nextBody, {
      claim: row.claim,
      kind: row.kind,
      holder: row.holder,
      weight: row.weight ?? 0.5,
      source: row.source,
      sinceDate: row.sinceDate,
      active: true,
    });
    nextBody = result.body;
    rowNums.push(result.rowNum);
  }
  return { body: nextBody, rowNums };
}

export async function addTakeToPage(
  target: TakesWriteTarget,
  input: AddTakeInput,
): Promise<{ rowNum: number; mirror: TakeMirror }> {
  assertHolderAllowed(input.holder, target.allowList);
  // Fence-injection + range guards run before any I/O (invalid input must
  // never acquire the lock or touch the page).
  assertSafeCellText('claim', input.claim);
  assertSafeCellText('kind', input.kind);
  assertSafeCellText('holder', input.holder);
  assertSafeCellText('source', input.source);
  assertValidWeight(input.weight);
  assertValidSinceDate(input.sinceDate);
  return withTakesLock(target, async () => {
    // Resolve the page BEFORE touching the markdown (the historical CLI
    // ordering): failing after a fence write would leave a take on disk the
    // DB never saw until the next reconcile.
    const pageId = await getPageId(target.engine, target.slug, target.sourceId);
    // add is the one mutate that may CREATE the page file + fence (first take
    // on a page) — readPageBody's existence refusal applies to row-targeting
    // mutates, not appends; the page itself was verified in the DB above.
    const { path, writeRoot } = await resolveTakesFilePath(
      target.engine, target.brainDir, target.slug, target.sourceId,
    );
    const body = await withStoredTakesFence(target.engine, pageId, existsSync(path) ? readFileSync(path, 'utf-8') : '');
    // F1: guard only fires when a fence ALREADY exists (an empty/fence-less body
    // parses to zero warnings) — a whole-fence re-render must not delete rows
    // this version couldn't parse.
    assertFenceRoundTrips(parseTakesFence(body));
    const { body: nextBody, rowNum } = upsertTakeRow(body, {
      claim: input.claim,
      kind: input.kind,
      holder: input.holder,
      weight: input.weight ?? 0.5,
      source: input.source,
      sinceDate: input.sinceDate,
      active: true,
    });
    writePageBody(path, nextBody, writeRoot, target.slug);
    let mirrorWarning: string | undefined;
    try {
      await maintenanceTransaction(target.engine, tx => tx.addTakesBatch([{
        page_id: pageId, row_num: rowNum, claim: input.claim, kind: input.kind,
        holder: input.holder, weight: input.weight ?? 0.5,
        since_date: input.sinceDate, source: input.source,
        active: true, superseded_by: null,
      }]), target.trust);
    } catch (err) {
      // P1-4/F4: md is canonical + already written — a failed DB mirror is
      // healed by the next reconcile, so surface a warning instead of throwing
      // (a throw would make the caller retry and duplicate the durable md row).
      mirrorWarning = mirrorErrorMessage(err);
    }
    return { rowNum, mirror: { written: true, path, ...(mirrorWarning ? { mirror_warning: mirrorWarning } : {}) } };
  });
}

/**
 * #4473 — md-first batch append for the takes-bootstrap lane
 * (extract-takes-from-pages.ts). MARKDOWN IS CANONICAL: the bootstrap
 * classifier used to call engine.addTakesBatch directly, minting DB-only rows
 * that the next md→DB reconcile / extract rebuild silently clobbered. This
 * routes the whole per-page batch through the same fence pipeline as
 * addTakeToPage (lock → page id → fence append → md write → DB mirror), with
 * two bootstrap-specific differences:
 *
 *   - `brainDir` may be null (sync.repo_path unset): a page whose source
 *     carries its own local_path still resolves; a host-repo page throws
 *     'mirror_unavailable' and the caller skips + counts it.
 *   - The page FILE must already exist. Bootstrap sweeps a whole corpus, and
 *     minting fence-only twin .md files for DB-born pages would recreate
 *     divergence at scale (#3605's stray-twin lesson) — a missing file is a
 *     per-page 'mirror_unavailable' skip, never a create.
 *
 * Row numbers derive from the fence (max existing + 1, appended in order),
 * so the historical (page_id, row_num=1) collision posture is gone.
 */
export async function appendTakesToPageMdFirst(
  target: Omit<TakesWriteTarget, 'brainDir'> & { brainDir: string | null },
  rows: ReadonlyArray<AddTakeInput>,
): Promise<{ rowNums: number[]; mirror: TakeMirror }> {
  for (const row of rows) {
    assertHolderAllowed(row.holder, target.allowList);
    assertSafeCellText('claim', row.claim);
    assertSafeCellText('kind', row.kind);
    assertSafeCellText('holder', row.holder);
    assertSafeCellText('source', row.source);
    assertValidWeight(row.weight);
    assertValidSinceDate(row.sinceDate);
  }
  return withTakesLock(target, async () => {
    const pageId = await getPageId(target.engine, target.slug, target.sourceId);
    const { path, writeRoot } = await resolveTakesFilePath(
      target.engine, target.brainDir, target.slug, target.sourceId,
    );
    // Unlike addTakeToPage, a missing file REFUSES (readPageBody's
    // mirror_unavailable) — see the contract note above.
    const body = await withStoredTakesFence(target.engine, pageId, readPageBody(path));
    const { body: nextBody, rowNums } = appendTakesToPageBody(body, rows);
    writePageBody(path, nextBody, writeRoot, target.slug);
    // Mirror md→DB with the reconcile primitive, exactly as the fence now
    // states the appended rows.
    const appended = new Set(rowNums);
    const after = parseTakesFence(nextBody).takes.filter(t => appended.has(t.rowNum));
    let mirrorWarning: string | undefined;
    try {
      await maintenanceTransaction(target.engine, tx => tx.addTakesBatch(after.map(t => toBatchInput(pageId, t))));
    } catch (err) {
      mirrorWarning = mirrorErrorMessage(err); // P1-4/F4: md written; DB mirror deferred to reconcile.
    }
    return { rowNums, mirror: { written: true, path, ...(mirrorWarning ? { mirror_warning: mirrorWarning } : {}) } };
  });
}

export interface UpdateTakeFields {
  weight?: number;
  source?: string;
  sinceDate?: string;
}

export async function updateTakeOnPage(
  target: TakesWriteTarget,
  rowNum: number,
  fields: UpdateTakeFields,
): Promise<{ rowNum: number; mirror: TakeMirror }> {
  if (fields.weight === undefined && fields.source === undefined && fields.sinceDate === undefined) {
    throw new TakesWriteError('no_fields', 'No mutable fields given (weight, source, since date).');
  }
  assertSafeCellText('source', fields.source);
  assertValidWeight(fields.weight);
  assertValidSinceDate(fields.sinceDate);
  return withTakesLock(target, async () => {
    const pageId = await getPageId(target.engine, target.slug, target.sourceId);
    const { path, writeRoot } = await resolveTakesFilePath(
      target.engine, target.brainDir, target.slug, target.sourceId,
    );
    const body = readPageBody(path);
    const parsed = parseTakesFence(body);
    assertFenceRoundTrips(parsed); // F1: refuse a whole-fence re-render that would drop skipped rows.
    const targetRow = findFenceRow(parsed.takes, rowNum, target.allowList, target.slug);
    if (targetRow.resolvedAt) {
      throw new TakesWriteError('already_resolved', `Row #${rowNum} on ${target.slug} is resolved — resolved takes are immutable.`, 'Supersede instead.');
    }
    if (!targetRow.active) {
      // A superseded row's mirror upsert would also wipe its superseded_by
      // pointer — refuse, matching supersedeTakeOnPage's guard.
      throw new TakesWriteError('row_inactive', `Row #${rowNum} on ${target.slug} is already superseded.`);
    }
    const updated: ParsedTake = {
      ...targetRow,
      weight: fields.weight ?? targetRow.weight,
      source: fields.source ?? targetRow.source,
      sinceDate: fields.sinceDate ?? targetRow.sinceDate,
    };
    const allRows = parsed.takes.map(t => (t.rowNum === rowNum ? updated : t));
    writePageBody(path, replaceFence(body, allRows), writeRoot, target.slug);
    // Mirror md→DB with the reconcile primitive (upsert on (page_id,row_num));
    // base columns only, resolution columns preserved by the DO UPDATE list.
    let mirrorWarning: string | undefined;
    try {
      await maintenanceTransaction(target.engine, tx => tx.addTakesBatch([toBatchInput(pageId, updated)]));
    } catch (err) {
      mirrorWarning = mirrorErrorMessage(err); // P1-4/F4: md written; DB mirror deferred to reconcile.
    }
    return { rowNum, mirror: { written: true, path, ...(mirrorWarning ? { mirror_warning: mirrorWarning } : {}) } };
  });
}

export interface SupersedeTakeInput {
  claim: string;
  kind?: TakeKind;
  holder?: string;
  weight?: number;
  source?: string;
  sinceDate?: string;
}

export async function supersedeTakeOnPage(
  target: TakesWriteTarget,
  rowNum: number,
  input: SupersedeTakeInput,
): Promise<{ oldRow: number; newRow: number; mirror: TakeMirror }> {
  assertSafeCellText('claim', input.claim);
  assertSafeCellText('kind', input.kind);
  assertSafeCellText('holder', input.holder);
  assertSafeCellText('source', input.source);
  assertValidWeight(input.weight);
  assertValidSinceDate(input.sinceDate);
  return withTakesLock(target, async () => {
    const pageId = await getPageId(target.engine, target.slug, target.sourceId);
    const { path, writeRoot } = await resolveTakesFilePath(
      target.engine, target.brainDir, target.slug, target.sourceId,
    );
    const body = readPageBody(path);
    const parsed = parseTakesFence(body);
    assertFenceRoundTrips(parsed); // F1: refuse a whole-fence re-render that would drop skipped rows.
    const targetRow = findFenceRow(parsed.takes, rowNum, target.allowList, target.slug);
    if (!targetRow.active) {
      throw new TakesWriteError('row_inactive', `Row #${rowNum} on ${target.slug} is already superseded.`);
    }
    if (targetRow.resolvedAt) {
      throw new TakesWriteError('already_resolved', `Row #${rowNum} on ${target.slug} is resolved — resolved takes are immutable.`, 'Add a new take instead.');
    }
    const holder = input.holder ?? targetRow.holder;
    // An explicit replacement holder must clear the fence too (an allow-listed
    // caller must not mint rows held by identities it can't see).
    if (input.holder !== undefined) assertHolderAllowed(input.holder, target.allowList);
    // CLI-parity default: unset weight decays the target's by 0.1.
    const weight = input.weight ?? Math.max(0, targetRow.weight - 0.1);
    const { body: nextBody, newRowNum } = supersedeRow(body, rowNum, {
      claim: input.claim,
      kind: input.kind ?? targetRow.kind,
      holder,
      weight,
      sinceDate: input.sinceDate,
      source: input.source,
    });
    writePageBody(path, nextBody, writeRoot, target.slug);
    // Mirror BOTH affected rows exactly as the fence now states them:
    // old → inactive + superseded_by pointer, new → active append.
    const after = parseTakesFence(nextBody).takes;
    const oldAfter = after.find(t => t.rowNum === rowNum);
    const newAfter = after.find(t => t.rowNum === newRowNum);
    const mirrorRows: TakeBatchInput[] = [];
    if (oldAfter) mirrorRows.push(toBatchInput(pageId, oldAfter, newRowNum));
    if (newAfter) mirrorRows.push(toBatchInput(pageId, newAfter, null));
    let mirrorWarning: string | undefined;
    try {
      await maintenanceTransaction(target.engine, tx => tx.addTakesBatch(mirrorRows));
    } catch (err) {
      mirrorWarning = mirrorErrorMessage(err); // P1-4/F4: md written; DB mirror deferred to reconcile.
    }
    return { oldRow: rowNum, newRow: newRowNum, mirror: { written: true, path, ...(mirrorWarning ? { mirror_warning: mirrorWarning } : {}) } };
  });
}

export type ResolveQuality = 'correct' | 'incorrect' | 'partial' | 'unresolvable';

export interface ResolveTakeInput {
  quality: ResolveQuality;
  /** Evidence text (stored as the resolution source). */
  evidence?: string;
  value?: number;
  unit?: string;
  resolvedBy: string;
}

export async function resolveTakeOnPage(
  target: TakesWriteTarget,
  rowNum: number,
  input: ResolveTakeInput,
): Promise<{ rowNum: number; quality: ResolveQuality; mirror: TakeMirror }> {
  assertSafeCellText('evidence', input.evidence);
  assertSafeCellText('unit', input.unit);
  assertSafeCellText('resolved_by', input.resolvedBy);
  return withTakesLock(target, async () => {
    const pageId = await getPageId(target.engine, target.slug, target.sourceId);
    const { path, writeRoot } = await resolveTakesFilePath(
      target.engine, target.brainDir, target.slug, target.sourceId,
    );
    const body = readPageBody(path);
    const parsed = parseTakesFence(body);
    assertFenceRoundTrips(parsed); // F1: refuse a whole-fence re-render that would drop skipped rows.
    const targetRow = findFenceRow(parsed.takes, rowNum, target.allowList, target.slug);
    if (targetRow.resolvedAt) {
      throw new TakesWriteError('already_resolved', `Row #${rowNum} on ${target.slug} is already resolved.`);
    }
    if (!targetRow.active) {
      // Resolving a superseded row would feed calibration with an already-
      // revised claim — resolve the replacement row instead.
      throw new TakesWriteError('row_inactive', `Row #${rowNum} on ${target.slug} is already superseded.`, 'Resolve the replacement row instead.');
    }
    // quality → outcome per the schema CHECK (v74): correct↔true,
    // incorrect↔false, partial/unresolvable↔NULL.
    const outcome = input.quality === 'correct' ? true
      : input.quality === 'incorrect' ? false : undefined;
    const updated: ParsedTake = {
      ...targetRow,
      resolvedAt: new Date().toISOString().slice(0, 10),
      resolvedQuality: input.quality,
      resolvedOutcome: outcome,
      resolvedEvidence: input.evidence,
      resolvedValue: input.value,
      resolvedUnit: input.unit,
      resolvedBy: input.resolvedBy,
    };
    const allRows = parsed.takes.map(t => (t.rowNum === rowNum ? updated : t));
    writePageBody(path, replaceFence(body, allRows), writeRoot, target.slug);
    // Resolution fields aren't in TakeBatchInput — mirror via resolveTake.
    // A drifted DB missing the row is self-healed md→DB (upsert the base row,
    // then resolve): the markdown is the truth being propagated.
    // One shared argument object so the self-heal retry can never silently
    // diverge from the primary call.
    const resolveArgs = {
      quality: input.quality,
      outcome,
      value: input.value,
      unit: input.unit,
      source: input.evidence,
      resolvedBy: input.resolvedBy,
    };
    // P1-4/F4: md is canonical + already written — a failed DB mirror (incl. a
    // failed self-heal) is healed by the next reconcile, so it surfaces as a
    // warning, never a throw (a throw would make the caller retry the durable
    // md write and duplicate the row).
    let mirrorWarning: string | undefined;
    try {
      await maintenanceTransaction(target.engine, tx => tx.resolveTake(pageId, rowNum, resolveArgs));
    } catch (err) {
      if (err instanceof Error && err.message.includes('TAKE_ROW_NOT_FOUND')) {
        try {
          await maintenanceTransaction(target.engine, async tx => {
            await tx.addTakesBatch([toBatchInput(pageId, targetRow)]);
            await tx.resolveTake(pageId, rowNum, resolveArgs);
          });
        } catch (healErr) {
          mirrorWarning = mirrorErrorMessage(healErr);
        }
      } else {
        mirrorWarning = mirrorErrorMessage(err);
      }
    }
    return { rowNum, quality: input.quality, mirror: { written: true, path, ...(mirrorWarning ? { mirror_warning: mirrorWarning } : {}) } };
  });
}

/** Pure fence primitives shared by durable semantic preparation and legacy callers. */
export const takesPreparation = { assertHolderAllowed, assertSafeCellText, assertValidWeight, assertValidSinceDate, findFenceRow, assertFenceRoundTrips, replaceFence, toBatchInput, toCanonicalBatchInput };