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
8.0 KB
Raw Blame
/**
 * Typed relation edges (v3 / typed graph semantics): the `links` rows
 * whose `relation` is set, the schema-pack constraints that block them,
 * and the endpoint resolution those reads share.
 *
 * Separate from `links.ts` because the reason to change is different:
 * this module follows the relation vocabulary and its constraints, not
 * the syntactic link rows themselves.
 */

import { Database } from "bun:sqlite";

import { sqlPlaceholders } from "./sql.ts";

/**
 * Endpoint resolution for a typed edge, as one SQL expression over a
 * `links` row aliased `l`. Wikilink-style relation targets are usually
 * bare ids (`[[note]]` -> `note`) that the generic `resolveLinkTargets`
 * exact-path pass cannot match against `note.md`, so the ladder also
 * tries `<target>.md` and - when unambiguous - a path-suffix match.
 * Ambiguous suffixes stay unresolved.
 *
 * Shared by all three typed-edge reads below so an edge cannot count as
 * resolved in one and dangling in another.
 */
const TYPED_RELATION_TARGET_SQL =
  "COALESCE(" +
  "    l.target_document_id, " +
  "    (SELECT d.id FROM documents d WHERE d.path = l.target_path || '.md'), " +
  "    (SELECT d.id FROM documents d " +
  "       WHERE SUBSTR(d.path, -(LENGTH(l.target_path) + 4)) = '/' || l.target_path || '.md' " +
  "       AND 1 = (SELECT COUNT(*) FROM documents d2 " +
  "                WHERE SUBSTR(d2.path, -(LENGTH(l.target_path) + 4)) = '/' || l.target_path || '.md'))" +
  "  )";

/**
 * The join that hangs both endpoints' `page_type` off a typed edge: the
 * source document is required, the target is whatever
 * {@link TYPED_RELATION_TARGET_SQL} resolves to.
 */
const TYPED_RELATION_ENDPOINTS_SQL =
  "FROM links l " +
  "JOIN documents sd ON sd.id = l.source_document_id " +
  "LEFT JOIN documents td ON td.id = " +
  TYPED_RELATION_TARGET_SQL +
  " ";

/**
 * For each document id, the typed relation edges it declares
 * (v3 / typed graph semantics): rows whose `relation` is set, in
 * insertion order. The target is the edge's `target_path` as written.
 * Documents with no typed edges are absent from the returned map.
 */
export function typedRelationsForDocuments(
  db: Database,
  documentIds: ReadonlyArray<number>,
): Map<number, Array<{ relation: string; target: string }>> {
  const out = new Map<number, Array<{ relation: string; target: string }>>();
  if (documentIds.length === 0) return out;
  const placeholders = sqlPlaceholders(documentIds);
  const rows = db
    .query<
      {
        source_document_id: number;
        relation: string;
        target_path: string | null;
      },
      number[]
    >(
      "SELECT source_document_id, relation, target_path FROM links " +
        `WHERE source_document_id IN (${placeholders}) AND relation IS NOT NULL ` +
        "AND relation_blocked = 0 " +
        "ORDER BY id",
    )
    .all(...(documentIds as number[]));
  for (const r of rows) {
    const target = r.target_path ?? "";
    if (target === "") continue;
    const arr = out.get(r.source_document_id);
    const edge = { relation: r.relation, target };
    if (arr) arr.push(edge);
    else out.set(r.source_document_id, [edge]);
  }
  return out;
}

/**
 * Typed relation edges declared by the given documents, with the
 * target resolved to a document id when possible (recall-trust-suite,
 * relation polarity). Ambiguous basenames stay unresolved
 * (deterministic inertness beats guessing the wrong page).
 */
export function typedRelationEdgesForDocuments(
  db: Database,
  documentIds: ReadonlyArray<number>,
): Array<{
  readonly sourceDocumentId: number;
  readonly relation: string;
  readonly target: string;
  readonly targetDocumentId: number | null;
}> {
  if (documentIds.length === 0) return [];
  const placeholders = sqlPlaceholders(documentIds);
  const rows = db
    .query<
      {
        source_document_id: number;
        relation: string;
        target_path: string | null;
        resolved_target_id: number | null;
      },
      number[]
    >(
      "SELECT l.source_document_id, l.relation, l.target_path, " +
        `  ${TYPED_RELATION_TARGET_SQL} AS resolved_target_id ` +
        "FROM links l " +
        `WHERE l.source_document_id IN (${placeholders}) AND l.relation IS NOT NULL ` +
        "AND l.relation_blocked = 0 " +
        "ORDER BY l.id",
    )
    .all(...(documentIds as number[]));
  const out: Array<{
    sourceDocumentId: number;
    relation: string;
    target: string;
    targetDocumentId: number | null;
  }> = [];
  for (const r of rows) {
    const target = r.target_path ?? "";
    if (target === "") continue;
    out.push({
      sourceDocumentId: r.source_document_id,
      relation: r.relation,
      target,
      targetDocumentId: r.resolved_target_id,
    });
  }
  return out;
}

/**
 * Recompute every typed edge's `relation_blocked` flag from the
 * current schema-pack constraints (write-time-integrity-governance).
 * Runs after `resolveLinkTargets` on every index pass, so removing a
 * constraint restores blocked edges on the next run without touching
 * files. Returns the rows that ended up blocked. With an empty
 * constraint map the pass only resets stale flags.
 */
export function recomputeRelationConstraintFlags(
  db: Database,
  constraints: Readonly<Record<string, ReadonlyArray<string>>>,
): Array<{
  readonly relation: string;
  readonly sourcePath: string;
  readonly targetPath: string;
  readonly sourceType: string;
  readonly targetType: string;
  readonly declared: ReadonlyArray<string>;
}> {
  const rows = db
    .query<
      {
        id: number;
        relation: string;
        blocked: number;
        source_path: string;
        source_type: string | null;
        target_path: string | null;
        target_type: string | null;
      },
      []
    >(
      "SELECT l.id, l.relation, l.relation_blocked AS blocked, " +
        "  sd.path AS source_path, sd.page_type AS source_type, " +
        "  l.target_path, td.page_type AS target_type " +
        TYPED_RELATION_ENDPOINTS_SQL +
        "WHERE l.relation IS NOT NULL",
    )
    .all();
  const block = db.query("UPDATE links SET relation_blocked = 1 WHERE id = ?");
  const unblock = db.query("UPDATE links SET relation_blocked = 0 WHERE id = ?");
  const violations: Array<{
    relation: string;
    sourcePath: string;
    targetPath: string;
    sourceType: string;
    targetType: string;
    declared: ReadonlyArray<string>;
  }> = [];
  for (const row of rows) {
    const declared = constraints[row.relation];
    const allowed =
      declared === undefined ||
      declared.length === 0 ||
      row.source_type === null ||
      row.target_type === null ||
      declared.includes(`${row.source_type}->${row.target_type}`);
    if (allowed) {
      if (row.blocked !== 0) unblock.run(row.id);
      continue;
    }
    if (row.blocked === 0) block.run(row.id);
    violations.push({
      relation: row.relation,
      sourcePath: row.source_path,
      targetPath: row.target_path ?? "",
      sourceType: row.source_type!,
      targetType: row.target_type!,
      declared: declared!,
    });
  }
  return violations;
}

/**
 * The typed edges currently blocked by link constraints, for lint
 * surfacing. Read-only over the flags the last index pass computed.
 */
export function blockedRelationRows(db: Database): Array<{
  readonly relation: string;
  readonly sourcePath: string;
  readonly targetPath: string;
  readonly sourceType: string | null;
  readonly targetType: string | null;
}> {
  return db
    .query<
      {
        relation: string;
        source_path: string;
        target_path: string | null;
        source_type: string | null;
        target_type: string | null;
      },
      []
    >(
      "SELECT l.relation, sd.path AS source_path, l.target_path, " +
        "  sd.page_type AS source_type, td.page_type AS target_type " +
        TYPED_RELATION_ENDPOINTS_SQL +
        "WHERE l.relation IS NOT NULL AND l.relation_blocked = 1 " +
        "ORDER BY sd.path, l.id",
    )
    .all()
    .map((r) => ({
      relation: r.relation,
      sourcePath: r.source_path,
      targetPath: r.target_path ?? "",
      sourceType: r.source_type,
      targetType: r.target_type,
    }));
}