Skip to content

Local-first 🧠 memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.

TypeScript
23.6 KB
Raw Blame
/**
 * Wikilink parsing helpers for the Brain layer.
 *
 * The Obsidian-flavoured wikilink shape is `[[target]]`, with optional
 * alias (`[[target|alias]]`) and anchor (`[[target#section]]`) suffixes.
 * Brain frontmatter writers always emit the bare `[[id]]` form, but the
 * parsers must tolerate the alias / anchor / folder-prefixed / `.md`-
 * suffixed variants because the on-disk artifacts are user-editable.
 *
 * Surface:
 *
 *   - {@link normaliseWikilinkTarget} extracts the bare target id from
 *     any of those shapes. Used by the doctor command (resolving
 *     `evidenced_by` / `supersedes` pointers against the Brain index)
 *     and by the query command (matching log payload values against a
 *     preference id).
 *
 *   - {@link parseWikilink} returns the target if the input is exactly
 *     a wikilink form (`^\[\[…\]\]$`), or `null` otherwise. Used by the
 *     dream loop's `evidenced_by` walker and the digest's tolerant
 *     contradiction-line parser, where the caller wants to distinguish
 *     "this is a wikilink" from "this is bare text".
 *
 * Both helpers are case-preserving and do NOT validate that the target
 * exists; that's a higher-layer concern (doctor cross-references against
 * the Brain index, dream relies on a follow-up `Map.has` check).
 */

import { basename } from "node:path";

/*
 * Canonical wikilink regex variants.
 *
 * Exactly one definition of the `[[...]]` syntax exists per contract;
 * every parser in the codebase imports the variant whose edge-case
 * behavior it needs instead of declaring a local copy:
 *
 *   - {@link WIKILINK_TARGET_RE}: target before any `|`/`#` suffix,
 *     suffix captured separately. Tolerates newlines inside the
 *     brackets (historical `vault.ts` behavior). For target extraction
 *     and merged-link rewriting.
 *   - {@link WIKILINK_ALIAS_RE}: target plus optional `|alias`
 *     capture, single-line only, `#` stays inside the target. For the
 *     search link/entity extractors.
 *   - {@link RICH_WIKILINK_RE}: whole bracket body in one capture,
 *     single-line only. For the link-graph parser/formatter which
 *     decomposes the body itself.
 *   - {@link WIKILINK_DETECT_RE}: presence check, no captures.
 *   - {@link ANCHORED_WIKILINK_RE} / {@link EXACT_WIKILINK_RE}:
 *     prefix-strip and whole-string forms used by the normalisers in
 *     this module.
 *
 * The `g`-flagged variants are shared module-level instances: use them
 * with `matchAll`/`replace` (which do not leak `lastIndex` state);
 * clone via `new RegExp(re)` before calling `exec`/`test` in a loop.
 */

/** Target capture with separate `[#|]suffix` capture; multi-line tolerant. */
export const WIKILINK_TARGET_RE = /\[\[([^\]|#]+)([#|][^\]]*)?\]\]/g;

/**
 * Target plus optional `|alias` capture; single-line, unicode mode.
 * The `u` flag is inherited from the entity extractor; the link
 * extractor formerly ran the same pattern without it - equivalent
 * here because the pattern only uses negated classes over BMP
 * delimiters.
 */
export const WIKILINK_ALIAS_RE = /\[\[([^\]\n|]+?)(?:\|([^\]\n]+))?\]\]/gu;

/** Whole bracket body in one capture; single-line. */
export const RICH_WIKILINK_RE = /\[\[([^\]\n]+)\]\]/g;

/** Presence check only; no captures, not global. */
export const WIKILINK_DETECT_RE = /\[\[[^\]\n]+\]\]/u;

/** Leading-wikilink prefix strip; body in one capture. */
export const ANCHORED_WIKILINK_RE = /^\[\[([^\]]+)\]\]/;

/** Whole-string wikilink form; body in one capture. */
export const EXACT_WIKILINK_RE = /^\[\[([^\]]+)\]\]$/;

/**
 * Whether the character at `index` is preceded by an ODD run of
 * backslashes - the CommonMark shape of "already escaped by the author":
 * `\[` renders as a literal `[`, so a sigil behind an odd run is data the
 * caller already escaped, never structure. The one rule both halves of the
 * wikilink family read: the neutralizer's detector skips such sigils (and
 * never re-escapes them), and every link reader treats the bracket behind
 * one as inert text.
 *
 * Pure and linear in the run length. Shared from here rather than copied
 * so the detector's skip and the readers' skip cannot drift into two
 * grammars.
 */
export function precededByOddBackslashRun(s: string, index: number): boolean {
  let n = 0;
  let i = index - 1;
  while (i >= 0 && s[i] === "\\") {
    n++;
    i--;
  }
  return n % 2 === 1;
}

/**
 * Whether the `[[...]]` regex match spanning `[start, end)` in `text`
 * opens AND closes on live brackets: an opening or closing bracket
 * preceded by an odd backslash run is escaped data, and opens or closes
 * no link. `end - 2` must be the first `]` of the match's closing `]]`,
 * which every pattern in this module's family guarantees.
 *
 * The link readers apply this to each of their matches so they agree with
 * the neutralizer's detector by construction: a span the detector leaves
 * (an escaped `[[`) extracts as nothing, and a span it escapes can never
 * leave extractable structure behind. `text` is whatever string the
 * reader ran its regex over - code-masked or raw - so the run check reads
 * the same bytes the match did.
 */
export function isLiveWikilinkSpan(text: string, start: number, end: number): boolean {
  if (precededByOddBackslashRun(text, start)) return false;
  return !precededByOddBackslashRun(text, end - 2);
}

/** The two characters a fence is built from. */
const BACKTICK = "`";
const TILDE = "~";

/** The shortest run of fence characters that opens or closes a fence. */
const FENCE_MIN_RUN = 3;

/** A whole run of three or more fence characters: `[start, start + len)`. */
interface FenceRun {
  readonly start: number;
  readonly len: number;
}

/**
 * Every whole run of three or more `ch`, left to right, and for each the
 * run that closes it: the next run of the same character at least as long
 * (next-greater-or-equal, one monotonic-stack pass from the right).
 */
function fenceClosers(text: string, ch: string): Map<number, FenceRun> {
  const runs: FenceRun[] = [];
  let i = text.indexOf(ch);
  while (i !== -1) {
    let end = i + 1;
    while (end < text.length && text[end] === ch) end++;
    if (end - i >= FENCE_MIN_RUN) runs.push({ start: i, len: end - i });
    i = text.indexOf(ch, end);
  }
  const closers = new Map<number, FenceRun>();
  const stack: FenceRun[] = [];
  for (let r = runs.length - 1; r >= 0; r--) {
    const run = runs[r]!;
    while (stack.length > 0 && stack.at(-1)!.len < run.len) stack.pop();
    const closer = stack.at(-1);
    if (closer !== undefined) closers.set(run.start, closer);
    stack.push(run);
  }
  return closers;
}

/**
 * Every whole run of one or two backticks, left to right, and for each the
 * run that closes it as an inline code span: the next run of exactly the
 * same length (the CommonMark rule). One pass from the right.
 */
function inlineClosers(text: string): Map<number, FenceRun> {
  const runs: FenceRun[] = [];
  let i = text.indexOf(BACKTICK);
  while (i !== -1) {
    let end = i + 1;
    while (end < text.length && text[end] === BACKTICK) end++;
    if (end - i < FENCE_MIN_RUN) runs.push({ start: i, len: end - i });
    i = text.indexOf(BACKTICK, end);
  }
  const closers = new Map<number, FenceRun>();
  const nextOfLength = new Map<number, FenceRun>();
  for (let r = runs.length - 1; r >= 0; r--) {
    const run = runs[r]!;
    const closer = nextOfLength.get(run.len);
    if (closer !== undefined) closers.set(run.start, closer);
    nextOfLength.set(run.len, run);
  }
  return closers;
}

/**
 * Code regions a wikilink or mention scan masks out, as `[start, end)`
 * pairs left to right: a fenced block or an inline code span. A fence is a
 * whole run of three or more backticks or tildes, and it closes on the next
 * whole run of the same character at least as long (the CommonMark rule),
 * consumed whole: a longer fence holding a shorter run stays masked.
 * Elsewhere a run of one or two backticks opens an inline span that closes
 * on the next run of exactly its length. A run with no closer is not a
 * region, and none of its marks opens one.
 *
 * One pass over the text plus one pass over the runs, so the cost is
 * linear whatever the runs look like. Shared by every link and mention
 * reader, so a stored excerpt never contributes links anywhere.
 */
export function codeRegions(text: string): Array<[number, number]> {
  const closers = new Map([
    ...fenceClosers(text, BACKTICK),
    ...fenceClosers(text, TILDE),
    ...inlineClosers(text),
  ]);
  const regions: Array<[number, number]> = [];
  let i = 0;
  while (i < text.length) {
    const ch = text[i];
    if (ch !== BACKTICK && ch !== TILDE) {
      i++;
      continue;
    }
    const closer = closers.get(i);
    if (closer !== undefined) {
      const end = closer.start + closer.len;
      regions.push([i, end]);
      i = end;
      continue;
    }
    // An unclosed run is literal text as a whole: skipping it keeps its last
    // mark from opening an inline span against an unrelated later backtick.
    while (i < text.length && text[i] === ch) i++;
  }
  return regions;
}

/** `text` with every {@link codeRegions} region replaced by `fill(region)`. */
export function maskCodeRegions(text: string, fill: (region: string) => string): string {
  let out = "";
  let last = 0;
  for (const [start, end] of codeRegions(text)) {
    out += text.slice(last, start) + fill(text.slice(start, end));
    last = end;
  }
  return out + text.slice(last);
}

/**
 * Strip wikilink decoration off `value` and return the bare target id.
 *
 * Recognises:
 *   - surrounding `[[…]]` brackets (only the first match wins)
 *   - `|alias` and `#anchor` suffixes (alias / anchor dropped)
 *   - leading folder segments (`folder/foo` → `foo`)
 *   - trailing `.md` extension
 *
 * Returns the input unchanged (minus a trim) when it isn't decorated;
 * callers can still distinguish bare text from "no input" via the empty
 * string.
 */
export function normaliseWikilinkTarget(value: string): string {
  let s = value.trim();
  // Strip surrounding wikilink brackets, retaining only the target.
  const wm = ANCHORED_WIKILINK_RE.exec(s);
  if (wm) s = wm[1]!.trim();
  return stripBasenameDecoration(s);
}

/**
 * Drop `|alias`, `#anchor`, leading folder segments, and trailing
 * `.md` from a wikilink body (everything between `[[` and `]]`).
 * Shared between {@link normaliseWikilinkTarget} and
 * {@link parseArtifactRef} — they apply the same Obsidian-flavoured
 * resolution rules to the post-bracket part of the link.
 */
/**
 * Drop a wikilink body's alias and anchor, keeping the target verbatim -
 * folder segments and `.md` included.
 *
 * The half of {@link stripBasenameDecoration} that removes DECORATION,
 * split out because a consumer that resolves a target to a vault path
 * needs exactly this and must not have the other half: collapsing
 * `Brain/preferences/pref-x.md|the rule` to `pref-x` turns a
 * path-shaped reference into a bare basename that resolves to no file,
 * which is a fail-open for any rule asked over it.
 */
export function stripWikilinkDecoration(body: string): string {
  let s = body.trim();
  const pipe = s.indexOf("|");
  if (pipe >= 0) s = s.slice(0, pipe).trim();
  const hash = s.indexOf("#");
  if (hash >= 0) s = s.slice(0, hash).trim();
  return s;
}

function stripBasenameDecoration(body: string): string {
  let s = stripWikilinkDecoration(body);
  s = basename(s);
  if (s.endsWith(".md")) s = s.slice(0, -".md".length);
  return s;
}

/**
 * The id prefixes this Brain owns: preferences, retired records, and
 * signals. Anything else a wikilink resolves to is user prose or a
 * cross-layer note, and is nobody here's to flag or to prune.
 */
const BRAIN_ID_RE = /^(pref|ret|sig)-/;

/**
 * Whether `target` — a bare id, normally straight out of
 * {@link normaliseWikilinkTarget} — names an artifact this Brain
 * manages.
 *
 * A predicate rather than an exported pattern: the two callers that
 * asked this question each carried their own copy of the regex, which is
 * one grammar in two places waiting to disagree about a fourth prefix.
 * Exposing the answer instead of the pattern is what keeps it single.
 */
export function isBrainArtifactId(target: string): boolean {
  return BRAIN_ID_RE.test(target);
}

/**
 * The prefix a rule wears on each side of its retirement.
 *
 * Deliberately narrower than {@link BRAIN_ID_RE}. `sig-` is a different
 * artifact, not a second spelling of the same one, so folding it away
 * would merge a signal into whatever rule happens to share its slug.
 * `pref-<slug>` and `ret-<slug>` are the SAME record before and after
 * `moveToRetired` renamed it, which is the only reason a strip is
 * correct here at all.
 */
const BRAIN_ID_PREFIX_RE = /^(?:pref-|ret-)/;

/**
 * Drop the `pref-` / `ret-` prefix from a bare Brain id, leaving the slug
 * both spellings share.
 *
 * Two call sites had grown their own copy of this pattern - the `brain
 * audit` CLI verb and its MCP twin, both resolving a caller-supplied id
 * onto the one audit trail that is keyed by the ORIGINAL `pref-<slug>`.
 * One grammar in two files is one prefix away from disagreeing, and this
 * module is where the grammar already lives.
 *
 * Trims before matching as well as after, so a padded argument yields the
 * slug rather than falling through the pattern with its prefix intact.
 */
export function stripBrainIdPrefix(id: string): string {
  return id.trim().replace(BRAIN_ID_PREFIX_RE, "").trim();
}

/**
 * Fold any spelling of a Brain artifact reference onto one key.
 *
 * `[[pref-foo]]`, `pref-foo`, `ret-foo`, `Brain/retired/ret-foo.md` and
 * `[[Brain/preferences/pref-foo.md|Foo]]` all reduce to `foo`. The
 * composition is {@link normaliseWikilinkTarget} (brackets, alias,
 * anchor, folder, `.md`) followed by {@link stripBrainIdPrefix} (the
 * rename), which is exactly the pair a reverse lookup across a
 * retirement needs on BOTH sides of the join.
 *
 * The prefix strip is unconditional, and that has a consequence worth
 * naming rather than discovering: a basename that merely begins with one
 * of the two prefixes is folded like an id, so a note called
 * `ret-rospective.md` keys as `rospective`, and `pref-foo` shares a key
 * with a note called `foo.md`. Both collisions are between a preference
 * slug and an ordinary note basename, which is a namespace this project
 * does not otherwise keep apart.
 *
 * A caller that cannot tolerate that must match on exact ids plus the
 * `aliases:` a retirement records, rather than on a fold. This function
 * is for the reverse-lookup join, where the cost of a collision is one
 * extra advisory row naming a consumer that does not consume - not a
 * mutation, and visible to whoever reads it.
 */
export function brainArtifactSlug(value: string): string {
  return stripBrainIdPrefix(normaliseWikilinkTarget(value));
}

/**
 * Return the bare target id if `value` is exactly a wikilink form
 * (`^\[\[…\]\]$` modulo surrounding whitespace), otherwise `null`.
 *
 * Unlike {@link normaliseWikilinkTarget}, this is anchored: a bare id or
 * a mixed string ("see [[foo]]" embedded in prose) yields `null`. Use
 * this when "is this a wikilink at all?" is the question being asked.
 *
 * Alias / anchor / folder / `.md` decoration on the target itself is
 * stripped via the same logic as `normaliseWikilinkTarget` so callers
 * get a clean id either way.
 */
export function parseWikilink(value: string): string | null {
  const m = EXACT_WIKILINK_RE.exec(value.trim());
  if (!m) return null;
  return normaliseWikilinkTarget(m[1]!);
}

/**
 * Inclusive 1-based line range extracted from an artifact wikilink
 * (`[[file:120-145]]` → `{start: 120, end: 145}`). Single-line form
 * (`[[file:120]]`) returns `{start: 120, end: 120}`.
 */
export interface ArtifactRange {
  readonly start: number;
  readonly end: number;
}

/**
 * Parse result for an `artifact` field in an `apply-evidence` event.
 *
 * `target` is the normalised wikilink basename (same shape as
 * {@link normaliseWikilinkTarget} returns). `range` is present iff a
 * well-formed `:N` or `:N-N` suffix was supplied. `malformedRange` is
 * `true` when a range suffix was supplied but failed validation —
 * the artifact is still recorded verbatim by the writer; the
 * `brain_doctor` lint surfaces the failure separately so callers can
 * fix it without losing the underlying event.
 *
 * Original input is preserved as `raw` so the lint message can quote
 * exactly what the user wrote.
 */
export interface ArtifactRefParse {
  readonly raw: string;
  readonly target: string;
  readonly range?: ArtifactRange;
  readonly malformedRange?: true;
  /** When the range suffix is present (well-formed or not). */
  readonly rangeText?: string;
}

const RANGE_SUFFIX_RE = /^(.*):([^:]*)$/;

/**
 * Parse the `artifact` field of an apply-evidence event.
 *
 * Accepts:
 *   - bare wikilink `[[file]]`
 *   - decorated `[[Folder/file.md|Alias]]`
 *   - **range form** `[[file:120-145]]` or `[[file:120]]`
 *   - bare (non-wikilink) text, in which case `target` is the
 *     normalised input minus any range suffix
 *
 * Returns a parse — `target` is always present (possibly empty for
 * empty input). `range` and `malformedRange` are mutually exclusive.
 */
export function parseArtifactRef(value: string): ArtifactRefParse {
  const raw = value;
  // Extract the inside of `[[…]]` if present; otherwise treat the
  // whole input as the target body. Keep the colon suffix here so we
  // can peel the range BEFORE the basename collapse — `Folder/file:120`
  // otherwise has its colon swallowed by `path.basename`.
  let body = value.trim();
  let wasWikilink = false;
  const wm = EXACT_WIKILINK_RE.exec(body);
  if (wm) {
    body = wm[1]!.trim();
    wasWikilink = true;
  }
  // Drop `|alias` before the range probe — otherwise the alias text
  // sits between the colon-range and the end of the string and the
  // suffix regex picks up the alias instead.
  const pipe = body.indexOf("|");
  if (pipe >= 0) body = body.slice(0, pipe).trim();

  // Peel `:range` off the END before applying normaliseWikilinkTarget.
  // The numeric heuristic keeps Windows-style paths (`C:foo`) and
  // IPv6 addresses out of the range branch.
  let preRange = body;
  let rangeText: string | undefined;
  const rm = RANGE_SUFFIX_RE.exec(body);
  if (rm) {
    const candidate = rm[2]!.trim();
    if (wasWikilink || /^[0-9-]+$/.test(candidate)) {
      preRange = rm[1]!.trim();
      rangeText = candidate;
    }
  }

  // Delegate the alias/anchor/folder/.md strip to the canonical
  // wikilink normaliser so both call sites stay in sync.
  const target = normaliseWikilinkTarget(preRange);

  if (rangeText === undefined) {
    return { raw, target };
  }

  const range = validateRangeText(rangeText);
  if (range === null) {
    return { raw, target, rangeText, malformedRange: true };
  }
  return { raw, target, rangeText, range };
}

/**
 * Maximum length of the wikilink title rendered by {@link renderPrefLink}
 * before truncation kicks in. Chosen so a `[[pref-…|title]]` link fits on
 * one Obsidian list-row at typical viewport widths.
 */
export const MAX_PREF_LINK_TITLE_LEN = 80;

/**
 * Render a wikilink to a Brain preference or retired artifact with a
 * human-readable title sourced from the `principle` field.
 *
 * The title is NFC-normalised, whitespace-collapsed, sanitised of
 * wikilink-breaking characters (`[`, `]`, `|`), and truncated to
 * {@link MAX_PREF_LINK_TITLE_LEN} at a word boundary (ellipsised when
 * cut). When the principle is missing or becomes empty after
 * sanitisation, the helper falls back to the bare `[[id]]` form so the
 * link remains resolvable through {@link normaliseWikilinkTarget} and
 * {@link parseWikilink} (both of which already strip `|alias`).
 *
 * Used by every Brain writer that emits a pref / retired reference;
 * signal and external-artifact wikilinks stay bare-id because they have
 * no useful title source.
 */
/** Where a wikilink renders to: Obsidian `[[wikilink]]` or portable `[markdown](path)`. */
export type LinkOutputFormat = "wikilink" | "markdown";

export function renderPrefLink(input: {
  readonly id: string;
  readonly principle?: string;
  readonly format?: LinkOutputFormat;
  readonly targetPath?: string;
}): string {
  const raw = input.principle ?? "";
  // Sanitisation pipeline, in order:
  //   1. NFC normalise so visually-equal inputs hash to the same bytes.
  //   2. Strip C0/C1 control chars except tab/newline (the whitespace
  //      collapse below handles those), zero-width joiners, BiDi
  //      overrides — these can spoof or break Obsidian rendering.
  //   3. Replace wikilink-breaking glyphs (`[`, `]`, `|`) with spaces.
  //   4. Collapse all whitespace runs to a single space, trim.
  const title = raw
    .normalize("NFC")
    .replace(/\r\n?/g, "\n")
    // C0 controls (00-1F) except \t \n; DEL (7F); C1 controls (80-9F).
    // eslint-disable-next-line no-control-regex
    .replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f-\x9f]/g, " ")
    // Format / BiDi-override characters that can cause visual spoofing
    // in Obsidian: zero-width space/joiner, LRM/RLM, BiDi embedding +
    // override + isolates, soft hyphen, BOM.
    .replace(/[​-‏‪-‮⁦-⁩­]/g, " ")
    .replace(/[[\]|]/g, " ")
    .replace(/\s+/g, " ")
    .trim();
  if (title.length === 0) {
    if (input.format === "markdown") {
      return renderMarkdownLink(input.id, inferBrainArtifactPath(input.id, input.targetPath));
    }
    return `[[${input.id}]]`;
  }
  // Measure the cap against code-point count (Array.from yields one
  // entry per Unicode scalar) rather than UTF-16 code units so a
  // string of 50 astral glyphs (100 code units, 50 code points) is
  // not forced into the truncation path when the cap is 80.
  const codepoints = Array.from(title);
  if (codepoints.length <= MAX_PREF_LINK_TITLE_LEN) {
    if (input.format === "markdown") {
      return renderMarkdownLink(title, inferBrainArtifactPath(input.id, input.targetPath));
    }
    return `[[${input.id}|${title}]]`;
  }
  // Truncate to the cap, then back off to the previous word boundary —
  // but only when one exists inside the window. A single oversized token
  // (no space inside the cap) gets a hard cut so we still produce a link
  // rather than dropping back to the bare-id fallback. Slicing happens
  // on code points so an emoji or astral glyph never gets bisected
  // into a lone surrogate before the ellipsis.
  let cutPoints = codepoints.slice(0, MAX_PREF_LINK_TITLE_LEN);
  const lastSpace = cutPoints.lastIndexOf(" ");
  if (lastSpace > 0) cutPoints = cutPoints.slice(0, lastSpace);
  const truncated = `${cutPoints.join("")}…`;
  if (input.format === "markdown") {
    return renderMarkdownLink(truncated, inferBrainArtifactPath(input.id, input.targetPath));
  }
  return `[[${input.id}|${truncated}]]`;
}

function inferBrainArtifactPath(id: string, targetPath?: string): string {
  if (targetPath) return targetPath;
  if (id.startsWith("ret-")) return `Brain/retired/${id}.md`;
  if (id.startsWith("pref-")) return `Brain/preferences/${id}.md`;
  return `Brain/${id}.md`;
}

function renderMarkdownLink(label: string, targetPath: string): string {
  return `[${label}](${encodeMarkdownTarget(targetPath)})`;
}

function encodeMarkdownTarget(targetPath: string): string {
  return encodeURI(targetPath).replace(/\)/g, "%29");
}

function validateRangeText(text: string): ArtifactRange | null {
  // Accepts `N` or `N-N`, both with 1-based positive integers and
  // `end >= start`. Anything else fails (zero, negative numbers,
  // reversed range, dangling dashes).
  const single = /^\d+$/.exec(text);
  if (single) {
    const n = parseInt(text, 10);
    if (n <= 0) return null;
    return { start: n, end: n };
  }
  const pair = /^(\d+)-(\d+)$/.exec(text);
  if (!pair) return null;
  const start = parseInt(pair[1]!, 10);
  const end = parseInt(pair[2]!, 10);
  if (!Number.isFinite(start) || !Number.isFinite(end)) return null;
  if (start <= 0 || end <= 0) return null;
  if (end < start) return null;
  return { start, end };
}