@remnic/belief-ledger 9.3.596

package/README.md

@@ -0,0 +1,70 @@
+# @remnic/belief-ledger
+
+A Remnic library for a personal belief and prediction ledger. It stores claims,
+predictions, and opinions as structured Remnic facts, retrieves prior claims that
+may conflict, asks a host LLM to classify the relationship, and tracks prediction
+calibration over time.
+
+This package is intentionally host-neutral:
+
+- It depends on `@remnic/core` public APIs.
+- It does not import OpenClaw, Hermes, or direct OpenAI clients.
+- Host adapters provide LLM access through `LedgerLlmAdapter`, or wrap Remnic's
+  existing `FallbackLlmClient` with `createFallbackLlmLedgerAdapter`.
+
+## Basic Usage
+
+```ts
+import { StorageManager } from "@remnic/core";
+import {
+  BeliefLedger,
+  RemnicLedgerStore,
+  createFallbackLlmLedgerAdapter,
+} from "@remnic/belief-ledger";
+
+const storage = new StorageManager("/path/to/remnic-memory");
+const store = new RemnicLedgerStore(storage);
+const llm = createFallbackLlmLedgerAdapter(fallbackLlmClient);
+
+const ledger = new BeliefLedger({ store, llm });
+
+const result = await ledger.capture({
+  text: "I think local-first memory tools will beat cloud-only memory tools by 2027.",
+});
+
+if (result.challenge) {
+  console.log(result.challenge.question);
+}
+```
+
+## What Gets Stored
+
+Claims are written as Remnic `fact` memories with:
+
+- `tags`: `belief-ledger`, claim kind, status, and optional domain.
+- `entityRef`: the first extracted entity when one exists.
+- `structuredAttributes`: stance, confidence, domain, entities, deadline,
+  evidence links, status, prediction outcome, and Brier score.
+
+That confirms issue #869's upstream requirements through the public core
+surface: custom metadata, entity-scoped retrieval inputs, and supersession via
+`StorageManager.supersedeMemory`.
+
+## Host LLM Access
+
+The package asks for a `LedgerLlmAdapter` rather than an API key. OpenClaw,
+Hermes, CLI, or app adapters can route the calls through their normal Remnic LLM
+path. For OpenClaw-backed Remnic runtimes, pass the existing gateway-backed
+`FallbackLlmClient` to `createFallbackLlmLedgerAdapter`.
+
+## Core Flows
+
+- `capture`: extract a structured claim, persist it, retrieve prior claims,
+  judge contradictions, and draft a Socratic challenge when needed.
+- `crossExamine`: run retrieval and LLM judging against an existing claim.
+- `supersede`, `split`, `resolve`, `snooze`, `ignore`: typed ledger actions
+  suitable for host tool/function surfaces.
+- `scoreDuePredictions`: find predictions past deadline, grade them from a
+  verdict source or return a user-verdict prompt.
+- `reflect`: compute calibration summaries, Brier score, flipped claims, and
+  dormant topics.

package/dist/index.d.ts

@@ -0,0 +1,319 @@
+import { MemoryFile, StorageManager, FallbackLlmOptions, FallbackLlmClient, MemoryFrontmatter } from '@remnic/core';
+
+type LedgerClaimKind = "claim" | "prediction" | "opinion";
+type LedgerStance = "for" | "against" | "uncertain" | "neutral";
+type LedgerClaimStatus = "active" | "superseded" | "resolved" | "snoozed" | "ignored";
+type LedgerJudgeClassification = "contradiction" | "evolution" | "refinement" | "unrelated";
+type LedgerPredictionVerdict = "true" | "false" | "mixed" | "unknown";
+interface LedgerTimeWindow {
+    start?: string;
+    end?: string;
+}
+interface LedgerClaimScope {
+    entities: string[];
+    domain?: string;
+    timeWindow?: LedgerTimeWindow;
+}
+interface LedgerResolution {
+    verdict: LedgerPredictionVerdict;
+    actualConfidence: number;
+    resolvedAt: string;
+    source?: string;
+    notes?: string;
+    brierScore?: number;
+}
+interface LedgerClaim {
+    id: string;
+    memoryId: string;
+    statement: string;
+    kind: LedgerClaimKind;
+    stance: LedgerStance;
+    confidence: number;
+    scope: LedgerClaimScope;
+    deadline?: string;
+    evidenceLinks: string[];
+    status: LedgerClaimStatus;
+    createdAt: string;
+    updatedAt: string;
+    supersedes?: string;
+    supersededBy?: string;
+    parentIds: string[];
+    snoozedUntil?: string;
+    ignoredAt?: string;
+    ignoredReason?: string;
+    resolution?: LedgerResolution;
+    sourceText?: string;
+    sourceMemory?: MemoryFile;
+}
+interface LedgerClaimDraft {
+    statement: string;
+    kind?: LedgerClaimKind;
+    stance: LedgerStance;
+    confidence: number;
+    scope?: Partial<LedgerClaimScope>;
+    deadline?: string;
+    evidenceLinks?: string[];
+}
+interface LedgerCaptureInput {
+    text: string;
+    now?: string;
+    source?: string;
+    sessionKey?: string;
+}
+interface LedgerExtractionRequest extends LedgerCaptureInput {
+    now: string;
+}
+interface LedgerJudgeRequest {
+    current: LedgerClaim;
+    prior: LedgerClaim;
+}
+interface LedgerJudgeResult {
+    priorClaimId: string;
+    classification: LedgerJudgeClassification;
+    confidence: number;
+    rationale: string;
+}
+interface LedgerChallengeRequest {
+    current: LedgerClaim;
+    contradictions: Array<{
+        claim: LedgerClaim;
+        judgment: LedgerJudgeResult;
+    }>;
+}
+interface LedgerChallenge {
+    question: string;
+    priorClaimIds: string[];
+    suggestedActions: Array<"supersede" | "split" | "resolve" | "ignore">;
+}
+interface LedgerPredictionGradeRequest {
+    claim: LedgerClaim;
+    verdictSource?: string;
+    now: string;
+}
+interface LedgerPredictionGrade {
+    verdict: LedgerPredictionVerdict;
+    actualConfidence: number;
+    rationale: string;
+    source?: string;
+}
+interface LedgerLlmAdapter {
+    extractClaim(request: LedgerExtractionRequest): Promise<LedgerClaimDraft>;
+    judgeClaimPair(request: LedgerJudgeRequest): Promise<LedgerJudgeResult>;
+    draftSocraticChallenge(request: LedgerChallengeRequest): Promise<LedgerChallenge>;
+    gradePrediction?(request: LedgerPredictionGradeRequest): Promise<LedgerPredictionGrade | null>;
+}
+interface LedgerRetrievalCandidate {
+    claim: LedgerClaim;
+    score: number;
+    reasons: string[];
+}
+interface LedgerSemanticRetrievalAdapter {
+    scoreClaims(request: {
+        query: LedgerClaim;
+        candidates: LedgerClaim[];
+        limit: number;
+    }): Promise<Array<{
+        claimId: string;
+        score: number;
+    }>>;
+}
+interface LedgerRerankerAdapter {
+    rerank(request: {
+        query: LedgerClaim;
+        candidates: LedgerRetrievalCandidate[];
+        limit: number;
+    }): Promise<LedgerRetrievalCandidate[]>;
+}
+interface LedgerRetrievalOptions {
+    limit?: number;
+    includeStatuses?: LedgerClaimStatus[];
+    now?: string;
+    semantic?: LedgerSemanticRetrievalAdapter;
+    reranker?: LedgerRerankerAdapter;
+}
+interface LedgerCrossExaminationStats {
+    candidatesConsidered: number;
+    judged: number;
+    contradictions: number;
+    unrelated: number;
+    observableFalsePositiveRate: number;
+}
+interface LedgerCrossExaminationResult {
+    claim: LedgerClaim;
+    candidates: LedgerRetrievalCandidate[];
+    judgments: LedgerJudgeResult[];
+    challenge?: LedgerChallenge;
+    stats: LedgerCrossExaminationStats;
+}
+interface LedgerCaptureResult extends LedgerCrossExaminationResult {
+    claim: LedgerClaim;
+}
+interface LedgerStore {
+    createClaim(input: Omit<LedgerClaim, "id" | "memoryId" | "sourceMemory">): Promise<LedgerClaim>;
+    getClaim(id: string): Promise<LedgerClaim | null>;
+    listClaims(filter?: {
+        statuses?: LedgerClaimStatus[];
+        kinds?: LedgerClaimKind[];
+    }): Promise<LedgerClaim[]>;
+    updateClaim(id: string, patch: Partial<LedgerClaim>): Promise<LedgerClaim>;
+    supersedeClaim(priorId: string, newId: string, reason: string): Promise<boolean>;
+}
+interface LedgerScoreDuePredictionsOptions {
+    now?: string;
+    verdictSources?: Record<string, string>;
+    limit?: number;
+}
+interface LedgerPredictionScoreResult {
+    claim: LedgerClaim;
+    status: "resolved" | "needs_user_verdict" | "skipped";
+    resolution?: LedgerResolution;
+    prompt?: string;
+    reason?: string;
+}
+interface LedgerReflectionOptions {
+    now?: string;
+    dormantAfterDays?: number;
+}
+interface LedgerCalibrationBin {
+    minConfidence: number;
+    maxConfidence: number;
+    count: number;
+    meanPredictedConfidence: number;
+    meanActualConfidence: number;
+    calibrationError: number;
+}
+interface LedgerDomainCalibration {
+    domain: string;
+    count: number;
+    brierScore: number;
+    meanPredictedConfidence: number;
+    meanActualConfidence: number;
+    tendency: "overconfident" | "underconfident" | "well_calibrated";
+}
+interface LedgerFlippedClaim {
+    rootClaimId: string;
+    claimIds: string[];
+    statements: string[];
+    flipCount: number;
+}
+interface LedgerDormantTopic {
+    topic: string;
+    lastClaimAt: string;
+    daysSilent: number;
+    claimCount: number;
+}
+interface LedgerReflectionReport {
+    generatedAt: string;
+    totalClaims: number;
+    activeClaims: number;
+    resolvedPredictions: number;
+    brierScore?: number;
+    calibrationBins: LedgerCalibrationBin[];
+    domains: LedgerDomainCalibration[];
+    flippedClaims: LedgerFlippedClaim[];
+    dormantTopics: LedgerDormantTopic[];
+}
+
+interface RemnicLedgerStoreOptions {
+    now?: () => Date;
+    source?: string;
+    writeEntityLinks?: boolean;
+}
+declare class RemnicLedgerStore implements LedgerStore {
+    private readonly storage;
+    private readonly now;
+    private readonly source;
+    private readonly shouldWriteEntityLinks;
+    constructor(storage: StorageManager, options?: RemnicLedgerStoreOptions);
+    createClaim(input: Omit<LedgerClaim, "id" | "memoryId" | "sourceMemory">): Promise<LedgerClaim>;
+    getClaim(id: string): Promise<LedgerClaim | null>;
+    listClaims(filter?: {
+        statuses?: LedgerClaimStatus[];
+        kinds?: LedgerClaimKind[];
+    }): Promise<LedgerClaim[]>;
+    updateClaim(id: string, patch: Partial<LedgerClaim>): Promise<LedgerClaim>;
+    supersedeClaim(priorId: string, newId: string, reason: string): Promise<boolean>;
+    private getLedgerMemoryById;
+    private readAllLedgerCandidateMemories;
+    private writeClaimMemory;
+    private restoreClaimBestEffort;
+    private writeSupersessionCorrectionBestEffort;
+    private claimFromMemorySafely;
+    private writeEntityLinksBestEffort;
+    private writeEntityLinks;
+}
+
+interface BeliefLedgerOptions {
+    store: LedgerStore;
+    llm: LedgerLlmAdapter;
+    retrieval?: LedgerRetrievalOptions;
+    now?: () => Date;
+}
+interface BeliefLedgerFromStorageOptions extends RemnicLedgerStoreOptions {
+    llm: LedgerLlmAdapter;
+    retrieval?: LedgerRetrievalOptions;
+}
+interface ResolveClaimInput {
+    verdict: "true" | "false" | "mixed" | "unknown";
+    actualConfidence: number;
+    source?: string;
+    notes?: string;
+    resolvedAt?: string;
+}
+declare class BeliefLedger {
+    private readonly store;
+    private readonly llm;
+    private readonly retrieval;
+    private readonly now;
+    constructor(options: BeliefLedgerOptions);
+    static fromStorage(storage: StorageManager, options: BeliefLedgerFromStorageOptions): BeliefLedger;
+    capture(input: LedgerCaptureInput): Promise<LedgerCaptureResult>;
+    crossExamine(claimOrId: LedgerClaim | string, options?: LedgerRetrievalOptions): Promise<LedgerCrossExaminationResult>;
+    supersede(priorId: string, newId: string, reason: string): Promise<boolean>;
+    split(priorId: string, parts: LedgerClaimDraft[], reason?: string): Promise<LedgerClaim[]>;
+    resolve(claimId: string, input: ResolveClaimInput): Promise<LedgerClaim>;
+    snooze(claimId: string, until: string): Promise<LedgerClaim>;
+    ignore(claimId: string, reason?: string): Promise<LedgerClaim>;
+    scoreDuePredictions(options?: LedgerScoreDuePredictionsOptions): Promise<LedgerPredictionScoreResult[]>;
+    reflect(options?: LedgerReflectionOptions): Promise<LedgerReflectionReport>;
+    private requireClaim;
+}
+
+interface FallbackLlmLedgerAdapterOptions extends FallbackLlmOptions {
+    agentId?: string;
+}
+declare function createFallbackLlmLedgerAdapter(client: FallbackLlmClient, options?: FallbackLlmLedgerAdapterOptions): LedgerLlmAdapter;
+
+declare function retrievePriorClaims(query: LedgerClaim, store: LedgerStore, options?: LedgerRetrievalOptions): Promise<LedgerRetrievalCandidate[]>;
+
+declare function buildReflectionReport(claims: LedgerClaim[], options?: LedgerReflectionOptions): LedgerReflectionReport;
+
+declare const LEDGER_TAG = "belief-ledger";
+declare const LEDGER_SCHEMA_VERSION = "1";
+type StringRecord = Record<string, string>;
+declare function normalizeClaimDraft(draft: LedgerClaimDraft, options: {
+    now: string;
+    sourceText?: string;
+}): Omit<LedgerClaim, "id" | "memoryId" | "sourceMemory">;
+declare function normalizeJudgeResult(raw: unknown, priorClaimId: string): LedgerJudgeResult;
+declare function normalizeChallenge(raw: unknown, priorClaimIds: string[]): LedgerChallenge;
+declare function normalizePredictionGrade(raw: unknown): LedgerPredictionGrade;
+declare function createResolution(input: {
+    verdict: LedgerPredictionVerdict;
+    actualConfidence: number;
+    resolvedAt: string;
+    source?: string;
+    notes?: string;
+    predictedConfidence: number;
+}): LedgerResolution;
+declare function computeBrierScore(predictedConfidence: number, actualConfidence: number): number;
+declare function roundMetric(value: number): number;
+declare function claimToStructuredAttributes(claim: LedgerClaim): StringRecord;
+declare function claimTags(claim: LedgerClaim): string[];
+declare function serializeClaimBody(claim: Pick<LedgerClaim, "statement" | "kind" | "stance" | "confidence" | "scope" | "deadline" | "evidenceLinks" | "status" | "resolution">): string;
+declare function claimFromMemory(memory: MemoryFile): LedgerClaim | null;
+declare function memoryFrontmatterPatchForClaim(claim: LedgerClaim): Partial<MemoryFrontmatter>;
+declare function remnicMemoryStatusForClaim(claim: Pick<LedgerClaim, "status">): NonNullable<MemoryFrontmatter["status"]>;
+declare function normalizeIsoTimestamp(field: string, value: unknown): string;
+
+export { BeliefLedger, type BeliefLedgerFromStorageOptions, type BeliefLedgerOptions, type FallbackLlmLedgerAdapterOptions, LEDGER_SCHEMA_VERSION, LEDGER_TAG, type LedgerCalibrationBin, type LedgerCaptureInput, type LedgerCaptureResult, type LedgerChallenge, type LedgerChallengeRequest, type LedgerClaim, type LedgerClaimDraft, type LedgerClaimKind, type LedgerClaimScope, type LedgerClaimStatus, type LedgerCrossExaminationResult, type LedgerCrossExaminationStats, type LedgerDomainCalibration, type LedgerDormantTopic, type LedgerFlippedClaim, type LedgerJudgeClassification, type LedgerJudgeRequest, type LedgerJudgeResult, type LedgerLlmAdapter, type LedgerPredictionGrade, type LedgerPredictionGradeRequest, type LedgerPredictionScoreResult, type LedgerPredictionVerdict, type LedgerReflectionOptions, type LedgerReflectionReport, type LedgerRerankerAdapter, type LedgerResolution, type LedgerRetrievalCandidate, type LedgerRetrievalOptions, type LedgerScoreDuePredictionsOptions, type LedgerSemanticRetrievalAdapter, type LedgerStance, type LedgerStore, type LedgerTimeWindow, RemnicLedgerStore, type RemnicLedgerStoreOptions, type ResolveClaimInput, buildReflectionReport, claimFromMemory, claimTags, claimToStructuredAttributes, computeBrierScore, createFallbackLlmLedgerAdapter, createResolution, memoryFrontmatterPatchForClaim, normalizeChallenge, normalizeClaimDraft, normalizeIsoTimestamp, normalizeJudgeResult, normalizePredictionGrade, remnicMemoryStatusForClaim, retrievePriorClaims, roundMetric, serializeClaimBody };