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
7.1 KB
Raw Blame
/**
 * Session-lineage resolution (continuity-hygiene-freshness suite).
 *
 * Single resolution point for "which conversation does this session id
 * belong to". Precedence: native payload fields, then the DECLARED work
 * identity (signals-that-survive, Unit 9), then the interim ledger
 * crutch, then flat. The last two rungs both live in `crutch.ts` and are
 * reached through one call, so the ledger is walked once and the
 * fail-closed guards - a session with history of its own, a predecessor
 * already continued from - are written once and apply to both. See
 * `types.ts` for the contract.
 *
 * Two entry points, following the sibling pattern this repository uses
 * wherever a diagnostic channel is grafted onto an established
 * signature: {@link resolveSessionLineageDetailed} carries the crutch's
 * named outcome, and {@link resolveSessionLineage} delegates to it and
 * discards everything but the lineage, so every pre-existing caller
 * stays byte-identical.
 */

import { CRUTCH_ABSTENTION, type CrutchOutcome, resolveCrutchLineage } from "./crutch.ts";
import type { LineageLedgerState } from "./ledger.ts";
import type { LineageHints, SessionLineage } from "./types.ts";
import {
  DEGRADATION_CODE,
  type DegradationNotice,
  emitDegradationNotice,
} from "../../integrity/degradation.ts";

export interface ResolveLineageOptions {
  /** Ledger state for the crutch path; omit to disable the crutch. */
  readonly ledger?: LineageLedgerState;
  /**
   * Sessions the ledger's gap sidecar records as dropped
   * (`lineageGapSessionIds`). Threaded straight into the crutch, where
   * it completes Rule 1: a session whose observation the writer lock
   * refused still has history, and without this it would be stitched
   * onto an unrelated parallel session.
   */
  readonly gapSessionIds?: ReadonlySet<string>;
  /** Clock injected by the caller (epoch ms). Required for the crutch. */
  readonly nowMs?: number;
  /**
   * Opt-in sink for degradation notices (context-integrity-gates).
   * Absent means no diagnostics are produced at all, which is why
   * adding the channel changed no existing caller.
   */
  readonly notices?: DegradationNotice[];
}

/** Lineage plus the evidence behind it. */
export interface SessionLineageResolution {
  readonly lineage: SessionLineage;
  /**
   * The named outcome of the ledger rungs - declared identity, then the
   * crutch - present only when they actually ran (a ledger was supplied
   * and the native payload did not already decide). A `linked` outcome
   * IS the lineage; an `abstained` one is why continuation was refused.
   */
  readonly crutch?: CrutchOutcome;
}

/** Site recorded on the notices this module emits. */
const RESOLVE_SITE = "brain.lineage.resolve";

/**
 * Abstentions worth reporting. `no-candidate`, `self-known` and
 * `no-workspace` are the ORDINARY flat path - a first session, a
 * parallel session, a host that reports no directory - and emitting a
 * notice for them would bury the three that mean a continuation was
 * available and refused.
 */
const REPORTABLE_ABSTENTIONS: ReadonlySet<string> = new Set([
  CRUTCH_ABSTENTION.ambiguous,
  CRUTCH_ABSTENTION.stale,
  CRUTCH_ABSTENTION.evidenceMissing,
  // Unit 9. Both mean a DECLARED identity named a predecessor and the
  // link was still refused, which is the loudest form of "available and
  // refused" this resolver can report.
  CRUTCH_ABSTENTION.laneConflict,
  CRUTCH_ABSTENTION.workAmbiguous,
]);

function readId(value: string | null | undefined): string | null {
  return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
}

const FLAT_SOURCE = "flat";

/** Resolve the lineage of one session id. Never throws. */
export function resolveSessionLineage(
  hints: LineageHints,
  opts: ResolveLineageOptions = {},
): SessionLineage {
  return resolveSessionLineageDetailed(hints, opts).lineage;
}

/**
 * Resolve the lineage of one session id AND report how it was decided.
 * Never throws: a refusal is a returned value, because this runs inside
 * capture paths that are fail-soft by contract.
 */
export function resolveSessionLineageDetailed(
  hints: LineageHints,
  opts: ResolveLineageOptions = {},
): SessionLineageResolution {
  const sessionId = hints.sessionId;

  // Native path: any genuine lineage field on the payload wins. A
  // parent or root equal to the session itself carries no information
  // (the deployed Hermes collapses parent into session_id exactly this
  // way) and is ignored.
  const parentRaw = readId(hints.parentSessionId);
  const rootRaw = readId(hints.rootSessionId);
  const parentId = parentRaw !== null && parentRaw !== sessionId ? parentRaw : null;
  const rootFromPayload = rootRaw !== null && rootRaw !== sessionId ? rootRaw : null;
  if (parentId !== null || rootFromPayload !== null) {
    // A payload that names only its direct parent must not promote
    // that parent to root blindly - in a chain A -> B -> C the parent
    // B itself descends from A. When the ledger knows the parent's own
    // lineage, inherit its root (and continue its depth count).
    const parentLineage = parentId !== null ? opts.ledger?.get(parentId)?.lineage : undefined;
    const inheritedRoot =
      parentLineage !== undefined && parentLineage.source !== FLAT_SOURCE
        ? parentLineage.rootId
        : null;
    const depthRaw = hints.compressionDepth;
    const depth =
      typeof depthRaw === "number" && Number.isInteger(depthRaw) && depthRaw >= 0
        ? depthRaw
        : parentId !== null
          ? (parentLineage !== undefined && parentLineage.source !== FLAT_SOURCE
              ? parentLineage.depth
              : 0) + 1
          : 0;
    return {
      lineage: Object.freeze({
        rootId: rootFromPayload ?? inheritedRoot ?? parentId ?? sessionId,
        parentId,
        depth,
        source: "payload" as const,
      }),
    };
  }

  // Declared work identity (Unit 9), then the interim inference for
  // hosts without native lineage fields. CRUTCH(t_1459706f).
  if (opts.ledger !== undefined) {
    const outcome = resolveCrutchLineage({
      sessionId,
      ...(hints.cwd !== undefined ? { cwd: hints.cwd } : {}),
      ledger: opts.ledger,
      nowMs: opts.nowMs ?? 0,
      ...(hints.workspace !== undefined ? { workspace: hints.workspace } : {}),
      ...(opts.gapSessionIds !== undefined ? { gapSessionIds: opts.gapSessionIds } : {}),
      ...(hints.workId !== undefined ? { workId: hints.workId } : {}),
      ...(hints.laneId !== undefined ? { laneId: hints.laneId } : {}),
    });
    if (outcome.kind === "linked") {
      return { lineage: outcome.lineage, crutch: outcome };
    }
    if (opts.notices !== undefined && REPORTABLE_ABSTENTIONS.has(outcome.reason)) {
      emitDegradationNotice(opts.notices, {
        code: DEGRADATION_CODE.sessionLinkAbstained,
        site: RESOLVE_SITE,
        detail: `${outcome.reason}: ${outcome.detail} (session ${sessionId})`,
      });
    }
    return { lineage: flat(sessionId), crutch: outcome };
  }

  return { lineage: flat(sessionId) };
}

function flat(sessionId: string): SessionLineage {
  return Object.freeze({
    rootId: sessionId,
    parentId: null,
    depth: 0,
    source: FLAT_SOURCE,
  });
}