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
21.5 KB
Raw Blame
/**
 * Materialise a note for an unresolved wikilink target (B3).
 *
 * Three places already KNOW a link target does not exist, and every one
 * of them stops at knowing. `link-graph/repair-lane.ts:236-239` decides
 * `skip-missing-target`. `deep-synthesis.ts:706` emits the advice "write
 * the missing note or fix the dangling link". `doctor/link-checks.ts`
 * emits `broken-backlinks` with a structured `target` and its `sources`.
 * Nothing materialises anything, so each of the three is a report an
 * operator has to act on by hand - in a project whose whole argument is
 * that a mechanism which must be invoked by hand will be missed.
 *
 * Nothing here is new machinery either. The bytes come from
 * {@link renderStub}, which the graph importer has used since it shipped.
 * The write is `createNote`, so the nine-step path envelope and the
 * `if_exists` disposition apply unchanged. The proof that a target is
 * really missing is `note-title-resolver.ts`, which is fail-closed and
 * lists candidates rather than guessing.
 *
 * ## The stub contains nothing invented
 *
 * Its title is the target the link spelled. Its body is a list of the
 * documents that referenced it, as wikilinks, which is the one fact the
 * index actually holds about a target that does not exist. There is no
 * prose, in any language, pretending to be the user's - a scaffolded note
 * that opened with a sentence nobody wrote would be worse than the
 * dangling link it replaced.
 *
 * ## Why the scan refuses instead of returning nothing
 *
 * `resolveLinkTargets` runs as a global post-pass but `replaceDocAliases`
 * runs only for the documents a run actually read, so a dangling count
 * taken after an incremental pass differs from one taken after a forced
 * full pass. An empty list from a partially-resolved index reads as "this
 * vault has no broken links", which is a clean bill of health for a vault
 * nobody finished measuring. `link-ratchet.ts:211-233` already models the
 * refusal - `unmeasurable("partial-resolution")`, verified from the
 * index's own state keys rather than documented - and this follows it.
 * An unmeasurable index is a distinct outcome from a clean one, and there
 * is no fallback that reports zero.
 */

import { statSync } from "node:fs";
import { dirname, join, posix } from "node:path";

import { ensureInsideVault, vaultRelative } from "../../path-safety.ts";
import { REDACTION_PLACEHOLDER } from "../../redactor.ts";
import { requireNextStep } from "../next-step.ts";
import { SEARCH_INDEX_MISSING_CODE } from "../diagnostics.ts";
import { renderStub } from "../portability/graph.ts";
import type { DanglingLinkTarget } from "../../search/store/links.ts";
import { createNote, type CreateNoteIfExists, type CreateNoteOutcome } from "./create-note.ts";
import {
  NoteTitleResolutionError,
  resolveNoteTarget as resolveNoteTitle,
} from "./note-title-resolver.ts";

// ----- Why a dangling scan could not answer ---------------------------------

/**
 * The state of one dangling-target scan. Three of the four members are
 * refusals, and that is the point: each names a different reason the
 * index could not be believed, and none of them is spelled as an empty
 * result.
 */
export const DANGLING_SCAN = Object.freeze({
  /** The index recorded a forced full pass as its last run; the list is real. */
  measured: "measured",
  /** No index database at the configured path. */
  indexMissing: "index_missing",
  /** An index exists and could not be opened or queried. */
  indexUnreadable: "index_unreadable",
  /** The last index run was not a forced full pass, so a count is not reproducible. */
  partialResolution: "partial_resolution",
} as const);

/** Closed union over {@link DANGLING_SCAN}. */
export type DanglingScan = (typeof DANGLING_SCAN)[keyof typeof DANGLING_SCAN];

/** Membership list, measurable first. */
export const DANGLING_SCANS: ReadonlyArray<DanglingScan> = Object.freeze(
  Object.values(DANGLING_SCAN),
);

/**
 * `unknown` rather than `string`: the value crosses the MCP and CLI JSON
 * boundaries, and the vocabulary census probes every guard with `null`,
 * `42` and `{}`.
 */
export function isDanglingScan(value: unknown): value is DanglingScan {
  return typeof value === "string" && (DANGLING_SCANS as ReadonlyArray<string>).includes(value);
}

/** What one scan found, or why it declined to say. */
export interface DanglingScanResult {
  readonly state: DanglingScan;
  /**
   * The unresolved targets. Empty unless the state is `measured` - and an
   * empty list under any other state means "not measured", never "none".
   */
  readonly targets: ReadonlyArray<DanglingLinkTarget>;
  /** Why the scan could not measure; `null` when it did. */
  readonly detail: string | null;
  /** The registered command that makes a measurement possible. */
  readonly nextCommand: string;
}

/**
 * The command that produces an index a dangling scan can believe.
 * Resolved from the diagnostics registry rather than written here, so a
 * registry rename fails at import instead of inside the refusal it was
 * meant to explain.
 */
const REINDEX_COMMAND = requireNextStep(SEARCH_INDEX_MISSING_CODE).nextCommand;

/** Default cap on targets returned by one scan. */
export const DANGLING_SCAN_DEFAULT_LIMIT = 100;

/**
 * The `limit` handed to `Store.listDangling` so it groups every
 * unresolved row rather than the first page of them.
 *
 * `listDangling` takes a required cap; there is no "all" spelling. The
 * caller's own limit cannot be that cap, because it has to be applied
 * after the ownership filter - see the call site.
 */
const UNBOUNDED_TARGETS = Number.MAX_SAFE_INTEGER;

function refusal(state: DanglingScan, detail: string): DanglingScanResult {
  return Object.freeze({
    state,
    targets: Object.freeze([]),
    detail,
    nextCommand: REINDEX_COMMAND,
  });
}

export interface ListDanglingOptions {
  /** Maximum targets returned. Defaults to {@link DANGLING_SCAN_DEFAULT_LIMIT}. */
  readonly limit?: number;
  /**
   * Owner scope the listing is filtered against
   * (a-label-is-not-a-boundary, U3). Absent / `null` filters nothing,
   * which is what both existing callers get.
   *
   * The predicate cannot be SQL - `documents` has no owner column
   * (`src/core/search/schema.ts:103-113`) - so it lands here, one layer
   * above `listDangling`, where the vault root is in hand and
   * `isPathOwnerVisible` can be asked. A target whose sources are ALL
   * filtered away is dropped WHOLE: the surviving `target` string is the
   * link spelling a hidden note wrote, so publishing it would name a
   * private page's title and confirm the existence of the note that
   * pointed at it.
   */
  readonly ownerScope?: string | null;
  /**
   * The vault-relative paths the caller may read at its reach, applied
   * the same way as {@link ListDanglingOptions.ownerScope}: a source the
   * caller may not read is dropped, and a target left with no source is
   * dropped whole. Absent filters nothing.
   */
  readonly readable?: (rel: string) => boolean;
}

/**
 * List the vault's unresolved wikilink targets from the search index,
 * refusing rather than reporting zero when the index cannot be believed.
 *
 * The search modules are reached through a deferred import for the same
 * reason `notes/lifecycle.ts` defers them: the search barrel imports back
 * into the Brain tree, and a static edge from a Brain note writer into it
 * is the shape the acyclic-import ratchet exists to keep out.
 */
export async function listDanglingTargets(
  vault: string,
  opts: ListDanglingOptions = {},
): Promise<DanglingScanResult> {
  const limit = Math.max(0, Math.floor(opts.limit ?? DANGLING_SCAN_DEFAULT_LIMIT));
  const { existsSync } = await import("node:fs");
  const { resolveSearchConfig } = await import("../../search/index.ts");
  const { LAST_FULL_INDEX_AT_STATE_KEY, LAST_INDEXED_AT_STATE_KEY, Store } =
    await import("../../search/store.ts");

  let config;
  try {
    config = resolveSearchConfig({ vault });
  } catch (err) {
    return refusal(DANGLING_SCAN.indexUnreadable, hostPathFree(err, vault, null));
  }
  if (!existsSync(config.dbPath)) {
    // The path is deliberately absent: `admin-tools.ts:137` says the same
    // thing the same way, and the caller already knows which vault it
    // asked about. `nextCommand` carries the remedy.
    return refusal(DANGLING_SCAN.indexMissing, "the vault has no search index yet");
  }

  let store;
  try {
    store = await Store.open(config, { mode: "read" });
  } catch (err) {
    return refusal(DANGLING_SCAN.indexUnreadable, hostPathFree(err, vault, config.dbPath));
  }
  try {
    const full = store.getState(LAST_FULL_INDEX_AT_STATE_KEY);
    const last = store.getState(LAST_INDEXED_AT_STATE_KEY);
    if (full === null || last === null || full !== last) {
      return refusal(
        DANGLING_SCAN.partialResolution,
        `last full index ${full ?? "(never)"} is not the last index run ${last ?? "(never)"}; ` +
          "a dangling list is only reproducible after a forced full pass",
      );
    }
    // The limit caps what the CALLER receives, so it is applied AFTER
    // the ownership filter, never before it. Asking the store for
    // `limit` targets and then hiding some of them silently returns
    // fewer rows than the caller asked for and than the vault holds -
    // and the shortfall is proportional to how much the other owner
    // wrote, which is the existence leak read off a row count. Ordering
    // it this way costs nothing: `listDangling` reads every unresolved
    // row out of sqlite regardless and applies `limit` while grouping.
    const scope = opts.ownerScope ?? null;
    const visible = await visibleTargets(
      vault,
      store.listDangling(UNBOUNDED_TARGETS),
      scope,
      opts.readable,
    );
    return Object.freeze({
      state: DANGLING_SCAN.measured,
      targets: Object.freeze(visible.slice(0, limit)),
      detail: null,
      nextCommand: REINDEX_COMMAND,
    });
  } catch (err) {
    return refusal(DANGLING_SCAN.indexUnreadable, hostPathFree(err, vault, config.dbPath));
  } finally {
    await store.close();
  }
}

/**
 * Drop the sources the scope may not see, and drop the WHOLE target when
 * none of them survives.
 *
 * Filtering `sources` alone would not close this: `target` is the link
 * text a hidden note wrote, so a target reachable only from hidden
 * sources publishes that note's private outbound link - and, when the
 * link was written by title, the private page's title with it. A target
 * that still has a visible source stays, because that source's own text
 * already names it to this caller.
 *
 * The owner-scope view is reached through a DEFERRED import for the same
 * reason the store is: it imports the search-side frontmatter cache, and
 * a static edge from a Brain note writer into the search tree is the
 * shape the acyclic-import ratchet exists to keep out.
 */
async function visibleTargets(
  vault: string,
  targets: ReadonlyArray<DanglingLinkTarget>,
  scope: string | null,
  readable: ((rel: string) => boolean) | undefined,
): Promise<ReadonlyArray<DanglingLinkTarget>> {
  if (scope === null && readable === undefined) return targets;
  const { ownerScopeView } = await import("../owner-scope-view.ts");
  const view = scope === null ? null : ownerScopeView(vault, scope);
  const kept: DanglingLinkTarget[] = [];
  for (const target of targets) {
    const sources = target.sources.filter(
      (source) =>
        (view === null || view.visible(source)) && (readable === undefined || readable(source)),
    );
    if (sources.length === 0) continue;
    kept.push(
      sources.length === target.sources.length
        ? target
        : Object.freeze({ target: target.target, sources: Object.freeze(sources) }),
    );
  }
  return Object.freeze(kept);
}

/**
 * `err`'s own message with this install's absolute host paths removed.
 *
 * The `detail` this returns crosses the MCP boundary and lands in model
 * context - the contract `src/mcp/tools.ts:94-118` states, and the reason
 * `vaultStoreReference` renders `vault://<hex>` instead of a vault path
 * unless `expose_host_paths` is set. A sqlite error embeds the database
 * file it failed on, so passing the raw message through told any agent
 * that called this on an unindexed or locked vault where the operator's
 * home directory is.
 *
 * Substitution rather than suppression: WHICH file the store failed on is
 * not information the caller needs (there is one), but WHAT the
 * filesystem said about it is the whole of the diagnosis. Longest first,
 * so the database path is replaced before the directory that contains it
 * can consume its prefix.
 */
function hostPathFree(err: unknown, vault: string, dbPath: string | null): string {
  const raw = err instanceof Error ? err.message : String(err);
  const hostPaths = (dbPath === null ? [vault] : [dbPath, dirname(dbPath), vault])
    .filter((candidate) => candidate.length > 0)
    .toSorted((a, b) => b.length - a.length);
  let out = raw;
  for (const hostPath of hostPaths) out = out.split(hostPath).join(REDACTION_PLACEHOLDER);
  return out;
}

// ----- Materialising one target ---------------------------------------------

/** Machine-readable reason a {@link scaffoldStub} call was refused. */
export type ScaffoldStubErrorCode =
  /** The target was empty after unwrapping its brackets. */
  | "empty_target"
  /** The target already resolves to a note, so nothing is missing. */
  | "target_resolves"
  /** The target names more than one existing note. */
  | "target_ambiguous"
  /** A declared source is not an existing Markdown file inside the vault. */
  | "unknown_source";

export class ScaffoldStubError extends Error {
  readonly code: ScaffoldStubErrorCode;
  /** Vault-relative candidate paths, populated only for `target_ambiguous`. */
  readonly candidates: ReadonlyArray<string>;
  constructor(
    code: ScaffoldStubErrorCode,
    message: string,
    candidates: ReadonlyArray<string> = [],
  ) {
    super(message);
    this.name = "ScaffoldStubError";
    this.code = code;
    this.candidates = Object.freeze([...candidates]);
  }
}

export interface ScaffoldStubInput {
  /** The unresolved wikilink target, e.g. `Projects/Foo` or `Foo`. */
  readonly target: string;
  /**
   * Explicit destination. Absent derives `<target>.md`, which is the
   * path the link itself named - so a pathed target lands where the link
   * pointed and a bare basename lands at the vault root, predictably,
   * rather than at a location this module guessed from the sources.
   */
  readonly path?: string;
  /** Documents that referenced the target; they become the stub's body links. */
  readonly sources?: ReadonlyArray<string>;
  /** Occupied-target policy, forwarded to `createNote`. Absent means refuse. */
  readonly ifExists?: CreateNoteIfExists;
  /** False (the default) resolves and plans, writing nothing. */
  readonly apply?: boolean;
  /**
   * Config file that names the writing agent, forwarded to `createNote`
   * for the note-write record (who-wrote-what, Task A). A stub is a note
   * like any other and is attributed like one.
   */
  readonly configPath?: string;
  /**
   * The vault-relative paths the caller may read at its reach. A source
   * it may not read is refused exactly as a missing one, and a refusal
   * about an occupied target names no note it may not read. Absent,
   * every note may be read.
   */
  readonly readable?: (rel: string) => boolean;
}

export interface ScaffoldStubResult {
  /** The target as the caller spelled it, minus decoration. */
  readonly target: string;
  /** Vault-relative path the stub would occupy, or does. */
  readonly path: string;
  /** False when this was a plan-only run. */
  readonly applied: boolean;
  /** What `createNote` did; `null` on a plan-only run. */
  readonly outcome: CreateNoteOutcome | null;
  /** The source documents whose wikilinks the stub's body carries, sorted. */
  readonly sources: ReadonlyArray<string>;
}

/** The `.md` suffix, matched case-insensitively by the path envelope. */
const MARKDOWN_SUFFIX = ".md";

/** `Projects/Foo.md` -> `Projects/Foo`; anything else unchanged. */
function withoutSuffix(path: string): string {
  return path.toLowerCase().endsWith(MARKDOWN_SUFFIX)
    ? path.slice(0, -MARKDOWN_SUFFIX.length)
    : path;
}

/** `Projects/Foo` -> `Foo`. */
function basenameOf(target: string): string {
  return target.split(posix.sep).at(-1) ?? target;
}

/**
 * Prove the target is really missing.
 *
 * Success from the title resolver is a REFUSAL here, and that inversion
 * is the whole check: it means a note already answers this link, so there
 * is nothing dangling and creating a second one would introduce the
 * ambiguity the resolver refuses. `ambiguous` is refused for the same
 * reason, one step further along - the link is not broken, it is
 * over-answered, and a third note makes it worse. Only `not_found` /
 * `path_not_found` is a target worth materialising.
 */
function assertMissing(
  vault: string,
  target: string,
  readable: ((rel: string) => boolean) | undefined,
): void {
  const shown = (rel: string): boolean => readable === undefined || readable(rel);
  let resolved: string | null = null;
  try {
    resolved = resolveNoteTitle(vault, target);
  } catch (err) {
    if (err instanceof NoteTitleResolutionError) {
      if (err.code === "ambiguous") {
        // Only the candidates the caller may read are named; with none, the
        // sentence ends without an empty list.
        const candidates = err.candidates.filter(shown);
        throw new ScaffoldStubError(
          "target_ambiguous",
          `target "${target}" already names more than one note; ` +
            "resolve the ambiguity rather than adding a third" +
            (candidates.length > 0 ? `: ${candidates.join(", ")}` : ""),
          candidates,
        );
      }
      if (err.code === "empty_target") {
        throw new ScaffoldStubError("empty_target", err.message);
      }
      return;
    }
    throw err;
  }
  throw new ScaffoldStubError(
    "target_resolves",
    `target "${target}" already resolves to ${shown(resolved) ? resolved : "a note"}; ` +
      "there is nothing to materialise",
  );
}

/**
 * Refuse a declared source that is not an existing Markdown file inside
 * the vault.
 *
 * The stub's whole claim is that nothing in it is invented: its title is
 * the target the link spelled and its body is the documents that
 * referenced it. `target` and `path` have always gone through the path
 * envelope, and `sources` went through nothing at all - so a caller
 * could hand this function three strings it made up and get a note whose
 * body cited three documents that do not exist, in a surface whose
 * documented selling point is that it cites rather than composes.
 *
 * Existence inside the vault is what can be checked here and it is
 * checked. Whether that document really carries the reference is the
 * INDEX's claim, and `action: "list"` is where a caller gets it from;
 * re-deriving it here would make a write depend on an index the write
 * path deliberately does not consult.
 */
function assertSourcesExist(
  vault: string,
  sources: ReadonlyArray<string>,
  readable: ((rel: string) => boolean) | undefined,
): void {
  for (const source of sources) {
    let abs: string;
    try {
      abs = ensureInsideVault(join(vault, source), vault);
    } catch {
      throw new ScaffoldStubError(
        "unknown_source",
        `source "${source}" is not a path inside the vault`,
      );
    }
    if (
      !source.toLowerCase().endsWith(MARKDOWN_SUFFIX) ||
      !statSync(abs, { throwIfNoEntry: false })?.isFile() ||
      // A note the caller may not read is answered as a missing one.
      (readable !== undefined && !readable(vaultRelative(abs, vault)))
    ) {
      throw new ScaffoldStubError(
        "unknown_source",
        `source "${source}" is not an existing Markdown note; a stub cites documents, it does not invent them`,
      );
    }
  }
}

/**
 * Materialise a stub note for one unresolved wikilink target.
 *
 * Dry run by default. Scaffolding is never a side effect of anything: the
 * repair lane's `skip-missing-target` stays its default decision, and
 * this function is reached only when a caller asked for it.
 */
export function scaffoldStub(vault: string, input: ScaffoldStubInput): ScaffoldStubResult {
  const target = withoutSuffix(input.target.trim());
  if (target.length === 0) {
    throw new ScaffoldStubError("empty_target", "scaffold target must not be empty");
  }
  assertMissing(vault, target, input.readable);

  const path = input.path ?? `${target}${MARKDOWN_SUFFIX}`;
  const sources = Object.freeze([...(input.sources ?? [])].toSorted());
  assertSourcesExist(vault, sources, input.readable);
  // Body links are the SOURCES, spelled the way a wikilink spells a note:
  // the vault-relative path without its extension. Nothing else about a
  // target that does not exist is known, so nothing else is written.
  const [frontmatter, body] = renderStub(
    basenameOf(target),
    sources.map((source) => withoutSuffix(source)),
    {},
  );

  if (input.apply !== true) {
    // The path is still resolved by the caller's next call, not guessed
    // here: a plan that reported a destination the envelope would refuse
    // is the misleading success this release removes. `createNote` is the
    // only thing that decides, so a plan reports the path it WOULD pass
    // and writes nothing.
    return Object.freeze({ target, path, applied: false, outcome: null, sources });
  }

  const created = createNote(vault, {
    path,
    frontmatter,
    content: body,
    ...(input.ifExists !== undefined ? { ifExists: input.ifExists } : {}),
    ...(input.configPath !== undefined ? { configPath: input.configPath } : {}),
  });
  return Object.freeze({
    target,
    path: created.path,
    applied: true,
    outcome: created.outcome,
    sources,
  });
}