Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
27.8 KB
Raw Blame
/**
 * Line grammar: typed facts and typed relations a human or an agent can type
 * in any editor, read with zero LLM calls.
 *
 *   - [preference] Prefers oat milk #coffee (since the almond allergy)
 *   - [event] @effective[2024-03,2024-09) Led the pricing rework
 *   - works_at [[companies/acme-example]] (since 2024)
 *   - "board member" @effective[2022,) [[companies/widget-co]]
 *
 * A fact line is a list item whose content starts with `[category]`; a
 * relation line is a list item whose content is one relation type followed by
 * exactly one link. Anything that does not match exactly stays ordinary text
 * and keeps today's behavior (the link keeps its inferred type), so a
 * sentence that happens to contain a link never invents a relation type.
 *
 * Guards keep transcripts, task lists and citations out: a category is one
 * token of letters, `_` and `-` (so `[00:00:11]`, `[2024-01-01]`, `[Source: x]`,
 * `[^1]`, `[ ]` and ids like `[D4]` never match), all-caps markers like
 * `[TODO]`, `[x]`/`[X]` task markers and a small stoplist are refused, and lines inside code, blockquotes, HTML
 * comments, the Facts/Takes fences and machine-written sections (Timeline,
 * See also, Related, Sources, ...) are never read. Template and dictionary
 * lines are refused too: a fact line whose text holds another bare `[Slot]`
 * (`- [Time] - [Event]`), whose claim starts with a separator or is only a
 * placeholder (`TBD`, `...`), or whose category is a lexicographic usage
 * label (`[noun]`, `[informal]`). Every guard reads one line only, so a
 * line's parse never depends on its neighbors.
 *
 * `@effective[start,end)` (alias `@valid`) is an inline validity range with
 * ISO dates (`YYYY`, `YYYY-MM`, `YYYY-MM-DD`, UTC); `[`/`]` are inclusive and
 * `(`/`)` exclusive, an empty side is open. Ranges normalize to a half-open
 * `[from, until)` pair of dates. Natural-language and relative dates are
 * refused and never peeled, so the text stays as written.
 *
 * Pure: no engine, no I/O. Offsets are UTF-16 code units into the input.
 */
import { stripCodeBlocks } from './markdown-code.ts';
import { inSuppressedRange, rolePriorSuppressedRanges } from './machine-sections.ts';

export type GrammarReason =
  | 'prose_tail' | 'two_links' | 'stoplist_type' | 'undeclared_type'
  | 'unknown_qualifier' | 'invalid_range'
  | 'template_slot' | 'separator_claim' | 'placeholder_claim' | 'usage_label' | 'type_punctuation';

/** Guard refusals: reported only when the page also holds a grammar line, or when asked (`explainGuards`). */
const GUARD_REASONS: ReadonlySet<GrammarReason> = new Set(['template_slot', 'separator_claim', 'placeholder_claim', 'usage_label']);

export interface EffectiveRange {
  /** Inclusive start date `YYYY-MM-DD`, or null when open. */
  from: string | null;
  /** Exclusive end date `YYYY-MM-DD`, or null when open. */
  until: string | null;
  /** The qualifier exactly as written. */
  raw: string;
}

export interface GrammarFact {
  line: number;
  category: string;
  kind: 'event' | 'preference' | 'commitment' | 'belief' | 'fact' | 'idea';
  claim: string;
  tags: string[];
  context: string | null;
  effective: EffectiveRange | null;
}

export interface GrammarRelation {
  line: number;
  /** Offsets of the whole line in the input. */
  start: number;
  end: number;
  type: string;
  context: string | null;
  effective: EffectiveRange | null;
}

export interface GrammarDiagnostic {
  line: number;
  reason: GrammarReason;
  text: string;
  message: string;
}

export interface LineGrammarResult {
  facts: GrammarFact[];
  relations: GrammarRelation[];
  diagnostics: GrammarDiagnostic[];
}

const FACT_KINDS = new Set(['event', 'preference', 'commitment', 'belief', 'fact', 'idea']);
// Letters, `_` and `-` only: digits mark ids and codes (`[D4]`, `[ENG-1]`, `[Q3]`), not categories.
const CATEGORY_RE = /^[A-Za-z][A-Za-z_-]{0,31}$/;
const TYPE_TOKEN_RE = /^[A-Za-z][A-Za-z0-9_-]{0,39}$/;
const CATEGORY_STOPLIST = new Set(['x', 'todo', 'done', 'wip']);
/** Lexicographic labels (parts of speech, register and region) mark dictionary entries, not fact categories. */
export const USAGE_LABELS: ReadonlySet<string> = new Set([
  'noun', 'verb', 'adj', 'adjective', 'adv', 'adverb', 'pron', 'pronoun', 'prep', 'preposition', 'conj', 'interj',
  'informal', 'formal', 'slang', 'colloquial', 'archaic', 'obsolete', 'dated', 'literary', 'figurative', 'vulgar',
  'offensive', 'dialect', 'regional', 'plural', 'singular', 'transitive', 'intransitive', 'abbr',
]);
// A bare `[Slot]` of category shape: not a link label `[x](url)` or `[x][ref]`, not part of `[[x]]`, `![x]` or `\[x]`.
const BARE_SLOT_RE = /(?<![[\\!\]])\[[A-Za-z][A-Za-z_-]{0,31}\](?![[(\]])/;
// A claim that starts with a separator (`- [Time] - [Event]`, `[Day] | ...`); `-40 degrees` is still a claim.
const SEPARATOR_CLAIM_RE = /^(?:[–—|=>]|[-/](?=\s|$))/;
const PLACEHOLDER_CLAIM_RE = /^(?:\.{3,}|…|tbd|tba|tbc|x{3,}|_{3,}|<[^<>]*>|\?{2,})$/i;
const DECORATED_TYPE_RE = /^(\*\*|__|`)?([A-Za-z][A-Za-z0-9_-]{0,39}?)(\*\*|__|`)?(:)?$/;
const TYPE_STOPLIST = new Set(['see', 'also', 'cf', 'via', 'and', 'or', 'with', 'from', 're', 'by', 'to', 'per', 'and/or']);
const LIST_ITEM_RE = /^([ \t]*)(?:[-*+]|\d{1,9}[.)])[ \t]+(.*)$/;
// Neither date group may contain a comma: with n commas and no closer, a group
// that could also eat commas made the engine retry every comma as the
// separator (quadratic on the page-write path, #6186).
const QUALIFIER_RE = /^@([A-Za-z][A-Za-z0-9_]*)([[(])([^\][(),]*),([^\][(),]*)([\])])(?=\s|$)/;
const QUALIFIER_BODY_RE = /^[^\][()]*/;
const QUALIFIER_LIKE_RE = /^@([A-Za-z][A-Za-z0-9_]*)[[(:]/;
const LINE_TEXT_MAX = 160;
// A trailing `[Source: ...]` citation (plain or wrapping a markdown link) is
// part of the brain's quality convention, not of the grammar: it is set aside
// before a line is read.
// Same language as /\[Source:(?:[^\][]|\[[^\]]*\]\([^)]*\))*\]\s*$/i, scanned by hand: on a long
// unclosed body the regex left JSC's JIT for its backtracking interpreter, a 20x cost step at ~100k chars.
function citationBodyEnd(text: string, from: number): number {
  let i = from;
  while (i < text.length) {
    const c = text[i];
    if (c === ']') return i;
    if (c !== '[') { i++; continue; }
    const close = text.indexOf(']', i + 1);
    if (close < 0 || text[close + 1] !== '(') return -1;
    const paren = text.indexOf(')', close + 2);
    if (paren < 0) return -1;
    i = paren + 1;
  }
  return -1;
}

/** `text` without a trailing `[Source: ...]` citation (plain or wrapping a markdown link). */
export function stripTrailingCitation(text: string): string {
  const lower = text.toLowerCase();
  for (let at = lower.indexOf('[source:'); at >= 0; at = lower.indexOf('[source:', at + 1)) {
    const end = citationBodyEnd(text, at + 8);
    if (end >= 0 && text.slice(end + 1).trim() === '') return text.slice(0, at);
  }
  return text;
}

/** Index of the first char at or after each position that is in `stops`, or `text.length`. */
function nextStop(text: string, stops: string): Int32Array {
  const next = new Int32Array(text.length + 1).fill(text.length);
  for (let i = text.length - 1; i >= 0; i--) next[i] = stops.includes(text[i]) ? i : next[i + 1];
  return next;
}

/**
 * `[[wikilinks]]` and `[markdown](links)` in order, without overlaps: the
 * matches of /\[\[[^\]\n]+\]\]|\[[^\][\n]+\]\([^)\n]+\)/g. A scan with
 * precomputed stop positions, so a long run of unclosed brackets costs linear
 * time where the regex rescanned the run from every bracket (#6186).
 */
export function findLinks(text: string): Array<{ index: number; text: string }> {
  const out: Array<{ index: number; text: string }> = [];
  if (!text.includes('[')) return out;
  const closeOrNl = nextStop(text, ']\n');
  const bracketOrNl = nextStop(text, '[]\n');
  const parenOrNl = nextStop(text, ')\n');
  for (let i = 0; i < text.length; i++) {
    if (text[i] !== '[') continue;
    let end = -1;
    if (text[i + 1] === '[') {
      const j = closeOrNl[i + 2];
      if (j > i + 2 && text[j] === ']' && text[j + 1] === ']') end = j + 2;
    }
    if (end < 0) {
      const k = bracketOrNl[i + 1];
      if (k > i + 1 && text[k] === ']' && text[k + 1] === '(') {
        const m = parenOrNl[k + 2];
        if (m > k + 2 && text[m] === ')') end = m + 1;
      }
    }
    if (end < 0) continue;
    out.push({ index: i, text: text.slice(i, end) });
    i = end - 1;
  }
  return out;
}

/** Normalize a written relation type: `worksAt`, `works-at`, `"works at"` -> `works_at`. */
export function normalizeRelationType(raw: string): string {
  return raw.trim().replace(/([a-z0-9])([A-Z])/g, '$1_$2').toLowerCase().replace(/[\s-]+/g, '_').replace(/_+/g, '_').replace(/^_|_$/g, '');
}

function validDate(y: number, m: number, d: number): boolean {
  const date = new Date(Date.UTC(y, m - 1, d));
  return date.getUTCFullYear() === y && date.getUTCMonth() === m - 1 && date.getUTCDate() === d;
}

/** A date token at its stated precision: the period start plus the start of the next period. */
function datePeriod(token: string): { start: string; next: string } | null {
  const m = /^(\d{4})(?:-(\d{2})(?:-(\d{2}))?)?$/.exec(token.trim());
  if (!m) return null;
  const y = Number(m[1]); const mo = m[2] ? Number(m[2]) : null; const d = m[3] ? Number(m[3]) : null;
  if (mo !== null && (mo < 1 || mo > 12)) return null;
  if (d !== null && !validDate(y, mo!, d)) return null;
  const iso = (date: Date) => date.toISOString().slice(0, 10);
  if (d !== null) return { start: iso(new Date(Date.UTC(y, mo! - 1, d))), next: iso(new Date(Date.UTC(y, mo! - 1, d + 1))) };
  if (mo !== null) return { start: iso(new Date(Date.UTC(y, mo - 1, 1))), next: iso(new Date(Date.UTC(y, mo, 1))) };
  return { start: iso(new Date(Date.UTC(y, 0, 1))), next: iso(new Date(Date.UTC(y + 1, 0, 1))) };
}

type QualifierParse =
  | { kind: 'none' }
  | { kind: 'ok'; range: EffectiveRange; length: number }
  | { kind: 'refused'; reason: 'unknown_qualifier' | 'invalid_range'; message: string };

/**
 * Parse an `@effective[...]` qualifier at the start of `text`. A qualifier-like
 * token that is not an accepted range is refused (and never peeled); plain
 * `@handles` and emails are not qualifiers at all.
 */
export function parseEffectiveQualifier(text: string): QualifierParse {
  const m = QUALIFIER_RE.exec(text);
  if (!m) {
    const like = QUALIFIER_LIKE_RE.exec(text);
    if (!like) return { kind: 'none' };
    const known = like[1] === 'effective' || like[1] === 'valid';
    const extraComma = known && (QUALIFIER_BODY_RE.exec(text.slice(like[0].length))?.[0].split(',').length ?? 0) > 2;
    return { kind: 'refused', reason: known ? 'invalid_range' : 'unknown_qualifier',
      message: extraComma
        ? 'A validity range has exactly one comma separating start and end: @effective[2024-01-01,2025-06-01).'
        : known
        ? 'A validity range takes ISO dates: @effective[2024-01-01,2025-06-01) — [ ] inclusive, ( ) exclusive, an empty side is open.'
        : `Only @effective[start,end) (alias @valid) is read; @${like[1]} stays plain text.` };
  }
  const [whole, kind, open, rawStart, rawEnd, close] = m;
  if (kind !== 'effective' && kind !== 'valid') {
    return { kind: 'refused', reason: 'unknown_qualifier', message: `Only @effective[start,end) (alias @valid) is read; @${kind} stays plain text.` };
  }
  const startTok = rawStart.trim(); const endTok = rawEnd.trim();
  const start = startTok ? datePeriod(startTok) : null;
  const end = endTok ? datePeriod(endTok) : null;
  if ((startTok && !start) || (endTok && !end)) {
    return { kind: 'refused', reason: 'invalid_range', message: 'Dates must be YYYY, YYYY-MM or YYYY-MM-DD (calendar-valid, UTC); natural-language and relative dates are not read.' };
  }
  const from = start ? (open === '[' ? start.start : start.next) : null;
  const until = end ? (close === ']' ? end.next : end.start) : null;
  if (from && until && from >= until) {
    return { kind: 'refused', reason: 'invalid_range', message: 'The range ends before it starts; write @effective[start,end) with start before end.' };
  }
  return { kind: 'ok', range: { from, until, raw: whole }, length: whole.length };
}

/** Index of the `(` that opens a balanced group closing exactly at the end of `text`, or -1. */
function trailingGroupStart(text: string): number {
  if (!text.endsWith(')')) return -1;
  let depth = 0;
  for (let i = text.length - 1; i >= 0; i--) {
    if (text[i] === ')') depth++;
    else if (text[i] === '(') { depth--; if (depth === 0) return i; }
  }
  return -1;
}

/** A leading YAML frontmatter block (`---` ... `---` with at least one `key:` line), as a range. */
function frontmatterRange(text: string): [number, number] | null {
  const m = /^---\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/.exec(text);
  return m && /^[A-Za-z_][\w-]*:/m.test(m[1]) ? [0, m[0].length] : null;
}

function excludedRanges(text: string): Array<[number, number]> {
  const ranges: Array<[number, number]> = [];
  const frontmatter = frontmatterRange(text);
  if (frontmatter) ranges.push(frontmatter);
  const masked = stripCodeBlocks(text, { onHtmlComment: (start, end) => ranges.push([start, end]) });
  ranges.push(...rolePriorSuppressedRanges(masked));
  return ranges;
}

function lineText(line: string): string {
  const t = line.trim();
  return t.length > LINE_TEXT_MAX ? `${t.slice(0, LINE_TEXT_MAX - 1)}…` : t;
}

/**
 * Parse every grammar line in a page body. `declaredTypes`, when given (the
 * active schema pack's link verbs), gates relation types: an undeclared type
 * falls back to inference and is reported with the nearest declared verb.
 */
export function parseLineGrammar(text: string, opts: { declaredTypes?: ReadonlySet<string> | null; explainGuards?: boolean } = {}): LineGrammarResult {
  const result: LineGrammarResult = { facts: [], relations: [], diagnostics: [] };
  const guarded: GrammarDiagnostic[] = [];
  if (!text.includes('- ') && !text.includes('* ') && !text.includes('+ ') && !/\d[.)] /.test(text)) return result;
  const masked = stripCodeBlocks(text, { onHtmlComment: () => {} });
  const excluded = excludedRanges(text);
  let offset = 0;
  let lineNo = 0;
  for (const rawLine of text.split('\n')) {
    lineNo++;
    const start = offset;
    offset += rawLine.length + 1;
    const line = rawLine.replace(/\r$/, '');
    const visible = masked.slice(start, start + line.length);
    if (!visible.trim() || /^\s*>/.test(visible) || inSuppressedRange(excluded, start)) continue;
    const item = LIST_ITEM_RE.exec(visible);
    if (!item) continue;
    // Masking keeps offsets, so the item's content sits at the same place in
    // the original line; structure is read from the masked text (links inside
    // code are not links), the fact text from the original.
    const visibleContent = stripTrailingCitation(item[2]).trim();
    // Read from the original item: masking can widen the marker's whitespace when the item opens with inline code.
    const content = stripTrailingCitation(LIST_ITEM_RE.exec(line)?.[2] ?? line.slice(line.length - item[2].length)).trim();
    if (!visibleContent || visibleContent.startsWith('\\')) continue;
    const note = (reason: GrammarReason, message: string) => (GUARD_REASONS.has(reason) ? guarded : result.diagnostics).push({ line: lineNo, reason, text: lineText(line), message });
    if (visibleContent.startsWith('[') && content.startsWith('[')) {
      const fact = parseFactContent(content, visibleContent, note);
      if (fact) result.facts.push({ line: lineNo, ...fact });
      continue;
    }
    const relation = parseRelationContent(visibleContent, content, opts.declaredTypes ?? null, note);
    if (relation) result.relations.push({ line: lineNo, start, end: start + line.length, ...relation });
  }
  if (guarded.length && (opts.explainGuards || result.facts.length || result.relations.length)) {
    result.diagnostics.push(...guarded);
    result.diagnostics.sort((a, b) => a.line - b.line);
  }
  return result;
}

const FACT_FORM = 'To state a typed fact, write `- [category] claim` with a real category, for example `- [preference] Prefers tea`.';

function parseFactContent(content: string, visibleContent: string, note: (reason: GrammarReason, message: string) => void): Omit<GrammarFact, 'line'> | null {
  const m = /^\[([^\][]*)\][ \t]+(\S.*)$/.exec(content);
  if (!m) return null;
  const category = m[1].trim();
  if (!CATEGORY_RE.test(category)) return null;
  // An all-caps token is a marker or acronym (`[TODO]`, `[WIP]`, `[NB]`), not a category.
  if (CATEGORY_STOPLIST.has(category.toLowerCase()) || (category.length > 1 && category === category.toUpperCase()) || /^[A-Z]{2,}[-_]/.test(category)) return null;
  if (USAGE_LABELS.has(category.toLowerCase())) {
    note('usage_label', `[${category}] is a dictionary usage label, so this line stays page text and is not read as a typed fact. ${FACT_FORM}`);
    return null;
  }
  // Structure comes from the masked text (code is not a slot), so read the remainder there.
  const visibleRest = /^\[[^\][]*\][ \t]+(\S.*)$/.exec(visibleContent)?.[1] ?? '';
  if (BARE_SLOT_RE.test(visibleRest)) {
    note('template_slot', `This line looks like an unfilled template ([${category}] followed by another [Slot]), so it stays page text and is not read as a typed fact. Leave templates as they are; ${FACT_FORM}`);
    return null;
  }
  if (SEPARATOR_CLAIM_RE.test(m[2])) {
    note('separator_claim', `The text after [${category}] starts with a separator, which marks a template or table row, so this line stays page text. ${FACT_FORM}`);
    return null;
  }
  let rest = m[2].trim();
  let effective: EffectiveRange | null = null;
  const q = parseEffectiveQualifier(rest);
  if (q.kind === 'ok') { effective = q.range; rest = rest.slice(q.length).trim(); }
  else if (q.kind === 'refused') note(q.reason, q.message);
  let context: string | null = null;
  const group = trailingGroupStart(rest);
  if (group > 0) { context = rest.slice(group + 1, -1).trim() || null; rest = rest.slice(0, group).trim(); }
  const tags = [...rest.matchAll(/(?:^|\s)#([A-Za-z][\w/-]*)/g)].map(t => t[1]);
  const claim = rest.replace(/(?:^|\s)#[A-Za-z][\w/-]*/g, '').replace(/\s+/g, ' ').trim();
  if (!claim) return null;
  if (PLACEHOLDER_CLAIM_RE.test(claim)) {
    note('placeholder_claim', `The claim after [${category}] is only a placeholder, so this line stays page text. Leave it until there is a real claim; ${FACT_FORM}`);
    return null;
  }
  const lower = category.toLowerCase();
  return { category, kind: (FACT_KINDS.has(lower) ? lower : 'fact') as GrammarFact['kind'], claim, tags, context, effective };
}

/** The declared verb a typo most likely meant: within two edits and a third of the word, else none. */
function nearest(type: string, declared: ReadonlySet<string>): string | null {
  let best: string | null = null; let bestScore = Infinity;
  for (const candidate of declared) {
    const d = levenshtein(type, candidate);
    if (d < bestScore) { bestScore = d; best = candidate; }
  }
  return bestScore <= 2 && bestScore <= Math.floor(type.length / 3) ? best : null;
}

function levenshtein(a: string, b: string): number {
  const row = Array.from({ length: b.length + 1 }, (_, i) => i);
  for (let i = 1; i <= a.length; i++) {
    let prev = row[0]; row[0] = i;
    for (let j = 1; j <= b.length; j++) {
      const tmp = row[j];
      row[j] = Math.min(row[j] + 1, row[j - 1] + 1, prev + (a[i - 1] === b[j - 1] ? 0 : 1));
      prev = tmp;
    }
  }
  return row[b.length];
}

function parseRelationContent(content: string, original: string, declared: ReadonlySet<string> | null,
  note: (reason: GrammarReason, message: string) => void): Omit<GrammarRelation, 'line' | 'start' | 'end'> | null {
  const links = findLinks(content);
  if (!links.length) return null;
  const first = links[0];
  let prefix = content.slice(0, first.index).trim();
  // Masking blanks inline code, so a backticked type is read from the original line at the same offsets.
  const linkAt = original.indexOf(first.text);
  const decorated = linkAt > 0 ? DECORATED_TYPE_RE.exec(original.slice(0, linkAt).trim()) : null;
  if (decorated && (decorated[1] || decorated[3] || decorated[4]) && (decorated[1] ?? '') === (decorated[3] ?? '')) {
    const type = normalizeRelationType(decorated[2]);
    if (type.includes('_') || declared?.has(type)) {
      note('type_punctuation', `"${type}" is wrapped in formatting or followed by a colon, so it is not read as a relation type and the link keeps its inferred type. Write it bare: \`- ${type} [[target]]\`.`);
    }
    return null;
  }
  let effective: EffectiveRange | null = null;
  // A qualifier may sit between the type and the link.
  const qualifierAt = prefix.search(/\s@[A-Za-z]/);
  let qualifierText = '';
  if (qualifierAt > 0) { qualifierText = prefix.slice(qualifierAt).trim(); prefix = prefix.slice(0, qualifierAt).trim(); }
  const quoted = /^(["'])([^"']+)\1$/.exec(prefix);
  const tokenOk = quoted ? /^[A-Za-z][A-Za-z0-9 _-]{0,39}$/.test(quoted[2]) : TYPE_TOKEN_RE.test(prefix);
  if (!tokenOk) return null;
  const type = normalizeRelationType(quoted ? quoted[2] : prefix);
  if (!type) return null;
  const explicit = type.includes('_') || !!quoted || (declared?.has(type) ?? false);
  if (TYPE_STOPLIST.has(type)) {
    if (explicit) note('stoplist_type', `"${type}" is too generic to be a relation type, so the link keeps its inferred type.`);
    return null;
  }
  if (links.length > 1) {
    if (explicit) note('two_links', 'A relation line names exactly one link; write one line per target.');
    return null;
  }
  let suffix = content.slice(first.index + first.text.length).trim();
  if (!qualifierText && suffix.startsWith('@')) {
    const q = parseEffectiveQualifier(suffix);
    if (q.kind === 'ok') { qualifierText = q.range.raw; suffix = suffix.slice(q.length).trim(); }
    else if (q.kind === 'refused') { note(q.reason, q.message); return null; }
  }
  let context: string | null = null;
  if (suffix) {
    const group = trailingGroupStart(suffix);
    if (group !== 0) {
      if (explicit) note('prose_tail', `Text after the link makes this a sentence, so "${type}" is not applied. Put extra words in one trailing (context).`);
      return null;
    }
    context = suffix.slice(1, -1).trim() || null;
  }
  if (qualifierText) {
    const q = parseEffectiveQualifier(qualifierText);
    if (q.kind === 'ok' && q.length === qualifierText.length) effective = q.range;
    else { note(q.kind === 'refused' ? q.reason : 'invalid_range', q.kind === 'refused' ? q.message : 'Only one @effective[start,end) qualifier may follow the type.'); return null; }
  }
  if (declared && declared.size && !declared.has(type)) {
    const near = nearest(type, declared);
    note('undeclared_type', near
      ? `"${type}" is not a link verb of the active schema pack, so the link keeps its inferred type. Did you mean ${near}?`
      : `"${type}" is not a link verb of the active schema pack, so the link keeps its inferred type. The pack has no verb for this relationship: declare one in the pack's link_types, or use add_link with a declared type.`);
    return null;
  }
  return { type, context, effective };
}

const TRUTHY = new Set(['true', '1', 'yes', 'on']);
const FALSY = new Set(['false', '0', 'no', 'off']);
/** A grammar boolean as written: true, false, null when unset, or 'invalid' for anything else. */
export function parseGrammarBoolean(value: string | null | undefined): boolean | null | 'invalid' {
  if (value == null) return null;
  const v = value.trim().toLowerCase();
  return TRUTHY.has(v) ? true : FALSY.has(v) ? false : 'invalid';
}

/** Defaults of the line-grammar settings (held-out verdicts H3 and H7). */
export const LINE_GRAMMAR_DEFAULTS = { enabled: false, allowUndeclaredTypes: false, effectiveRanges: true } as const;
export const LINE_GRAMMAR_KEYS = ['line_grammar.enabled', 'line_grammar.allow_undeclared_types', 'line_grammar.effective_ranges'] as const;
/**
 * Internal config row: when the effective line-grammar behavior last changed.
 * Link extraction treats pages extracted before it as stale (see
 * core/link-extraction-watermark.ts). Not a user setting; `config unset`
 * refuses `_internal.*` keys.
 */
export const LINK_EXTRACTION_GENERATION_KEY = '_internal.link_extraction_generation';

export interface LineGrammarSettings {
  enabled: boolean;
  allowUndeclaredTypes: boolean;
  /** Ranges are stored only while the grammar is on. */
  effectiveRanges: boolean;
  /** ISO time of the last effective change, or null when never changed. */
  generation: string | null;
}

const resolveBoolean = (value: string | null, fallback: boolean) => { const v = parseGrammarBoolean(value); return typeof v === 'boolean' ? v : fallback; };

/** Settings from raw config values (unset or unreadable spellings take the default). */
export function lineGrammarSettingsFrom(raw: { enabled: string | null; allow: string | null; ranges: string | null; generation: string | null }): LineGrammarSettings {
  const enabled = resolveBoolean(raw.enabled, LINE_GRAMMAR_DEFAULTS.enabled);
  return { enabled, allowUndeclaredTypes: resolveBoolean(raw.allow, LINE_GRAMMAR_DEFAULTS.allowUndeclaredTypes),
    effectiveRanges: enabled && resolveBoolean(raw.ranges, LINE_GRAMMAR_DEFAULTS.effectiveRanges), generation: raw.generation };
}

/**
 * The line-grammar settings link extraction runs under, read once. Strict: a
 * failed config read throws, so the caller leaves the page stale instead of
 * extracting under defaults it did not mean.
 */
export async function readLineGrammarSettings(engine: { getConfig(key: string): Promise<string | null> }): Promise<LineGrammarSettings> {
  const [enabled, allow, ranges, generation] = await Promise.all([...LINE_GRAMMAR_KEYS, LINK_EXTRACTION_GENERATION_KEY].map(key => engine.getConfig(key)));
  return lineGrammarSettingsFrom({ enabled, allow, ranges, generation });
}

/** What extraction actually does under these settings; two settings with the same fingerprint extract identically. */
export function lineGrammarFingerprint(s: Pick<LineGrammarSettings, 'enabled' | 'allowUndeclaredTypes' | 'effectiveRanges'>): string {
  return s.enabled ? `on|undeclared:${s.allowUndeclaredTypes}|ranges:${s.effectiveRanges}` : 'off';
}

/** `line_grammar.enabled` and `line_grammar.allow_undeclared_types`, best-effort (read failures take the defaults); for advisories and lint. */
export async function lineGrammarOptions(engine: { getConfig(key: string): Promise<string | null> }): Promise<{ enabled: boolean; allowUndeclaredTypes: boolean }> {
  const read = (key: string) => engine.getConfig(key).catch(() => null);
  const [enabled, allow] = await Promise.all([read('line_grammar.enabled'), read('line_grammar.allow_undeclared_types')]);
  const s = lineGrammarSettingsFrom({ enabled, allow, ranges: null, generation: null });
  return { enabled: s.enabled, allowUndeclaredTypes: s.allowUndeclaredTypes };
}

/** `line_grammar.effective_ranges` (default on; applies only while `line_grammar.enabled` is on): store relation-line ranges on edges (core/link-effective.ts). */
export async function effectiveRangesEnabled(engine: { getConfig(key: string): Promise<string | null> }): Promise<boolean> {
  const read = (key: string) => engine.getConfig(key).catch(() => null);
  const [ranges, enabled] = await Promise.all([read('line_grammar.effective_ranges'), read('line_grammar.enabled')]);
  return lineGrammarSettingsFrom({ enabled, allow: null, ranges, generation: null }).effectiveRanges;
}

/**
 * The stated relation type for a link at `index` in `text`, for link
 * extraction. `declaredVerbs` (the active pack's link verbs) gates types
 * unless `allowUndeclaredTypes`; `enabled: false` turns stated types off.
 */
export function statedRelationTypes(text: string, opts: { enabled?: boolean; allowUndeclaredTypes?: boolean;
  declaredVerbs?: readonly string[] }): (index?: number) => string | undefined {
  if (opts.enabled === false) return () => undefined;
  const declaredTypes = !opts.allowUndeclaredTypes && opts.declaredVerbs?.length ? new Set(opts.declaredVerbs) : null;
  const lines = parseLineGrammar(text, { declaredTypes }).relations;
  if (!lines.length) return () => undefined;
  return index => index === undefined || index < 0 ? undefined : lines.find(line => index >= line.start && index < line.end)?.type;
}