@oortmem/core 0.5.1 → 0.5.2

package/dist/judgment.d.ts

@@ -0,0 +1,526 @@
+import type { DecisionController, Embedder, MemoryStore } from './adapters.js';
+import { type Grant } from './grant.js';
+import { type Decision, type Memory, type Scope } from './model.js';
+/**
+ * Judgment memory (CON-71): an expert's approve or reject decisions, with their reasons in their
+ * own words, kept so an agent can apply them to a new item, say why, and say when it is not sure.
+ *
+ * A judgment is a `judgment` memory whose `judgment` field holds the decision. It is written only
+ * through the judgment functions here (never inferred from a conversation), its reason is never
+ * paraphrased (the write path skips judgments), and it is pinned so it never loses its embedding
+ * to cold.
+ *
+ * Who recorded it matters. A judgment recorded by a person (the CLI, a bulk import) counts when
+ * judging. One recorded by an agent over MCP (`via: 'mcp'`) is agent-recorded and unconfirmed: it
+ * never corrects a person's judgment, and judging leaves it out until a person confirms it
+ * (`confirmJudgment`, CLI only) or the caller asks for agent-recorded judgments explicitly. One
+ * imported from a pack names an expert only as the pack states it, so judging leaves it out unless
+ * asked.
+ */
+/** The verdict set a judgment uses when none is given. */
+export declare const DEFAULT_VERDICTS: readonly string[];
+export declare const JUDGMENT_LIMITS: Readonly<{
+    summary: 500;
+    ref: 2000;
+    reason: 2000;
+    details: 4000;
+    criteria: 12;
+    criterion: 64;
+    verdicts: 12;
+    by: 128;
+    /** Rows one bulk import or pack may hold; a larger one is refused before anything is written. */
+    importRows: 5000;
+}>;
+/** What was judged: a summary, and where the item itself lives. */
+export interface JudgmentSubject {
+    summary: string;
+    /** A link or id of the item (a URL, a ticket, a file path). */
+    ref?: string;
+}
+/**
+ * Where a judgment came from, besides the expert who made it. `mcp` means an agent recorded it:
+ * agent-recorded, unconfirmed until a person confirms it.
+ */
+export type JudgmentVia = 'cli' | 'mcp' | 'import' | 'pack' | 'sdk';
+/**
+ * A judgment that arrived in a pack: the pack it was imported from here (its digest id and the
+ * manifest's name, exporter and time, all bound by the digest) and the id the line carried. Every
+ * field comes from the pack this store imported, never from what a line claims about itself.
+ */
+export interface JudgmentPackOrigin {
+    /** The pack's digest id (the first 16 hex characters of `packDigest`). */
+    id: string;
+    name: string;
+    exportedAt: string;
+    /** The agent that exported it. */
+    exportedBy: string;
+    /** The id the judgment had in the pack (its id in the exporting store). */
+    originalId: string;
+    importedAt: string;
+    /**
+     * What the line said about an earlier pack it came from, when the exporter had imported it
+     * itself. Untrusted: the exporter could have written anything here, so nothing uses it for
+     * deduplication, attribution or judging; it is kept only to be shown as a claim.
+     */
+    claimedEarlier?: ClaimedPackOrigin;
+}
+/** An earlier pack origin as a pack line claims it. Checked for shape only; never trusted. */
+export interface ClaimedPackOrigin {
+    untrusted: true;
+    id: string;
+    name: string;
+    exportedAt: string;
+    exportedBy: string;
+    originalId: string;
+}
+/** The decision itself. Everything an expert said is kept as they said it (secrets redacted). */
+export interface Judgment {
+    subject: JudgmentSubject;
+    /** One of `verdicts`. */
+    verdict: string;
+    /** The defined set the verdict comes from; `approved` and `rejected` by default. */
+    verdicts: string[];
+    /** The expert's own words. */
+    reason: string;
+    /** Tags the reason relies on (`no-source`, `pii`). */
+    criteria: string[];
+    domain: string;
+    /** The expert's id. */
+    by: string;
+    decidedAt: string;
+    /** How it was recorded. The agent that recorded it is the memory's author. */
+    via: JudgmentVia;
+    /** Set when it was withdrawn (and by which operator): it no longer counts anywhere. */
+    withdrawn?: {
+        at: string;
+        by: string;
+    };
+    /** Set on an agent-recorded (`mcp`) judgment a person confirmed: it then counts when judging. */
+    confirmed?: {
+        at: string;
+        by: string;
+    };
+    /** Set when its text was purged: only an audit stub (expert, domain, verdict, times) is left. */
+    purged?: {
+        at: string;
+        by: string;
+    };
+    /**
+     * Set when it was withdrawn, corrected or purged: `tombstoneKey` of the decision as it was, so no
+     * import brings the same decision back (it leaves out `decidedAt`, which a pack could shift).
+     */
+    tombstone?: string;
+    /** Set on a judgment imported from a pack. */
+    pack?: JudgmentPackOrigin;
+}
+/** A judgment's decision fields, as `normaliseJudgment` returns them. */
+export type JudgmentCore = Omit<Judgment, 'via' | 'pack' | 'withdrawn' | 'confirmed' | 'purged' | 'tombstone'>;
+/** A judgment as a caller describes it, before checking and normalising. */
+export interface JudgmentInput {
+    subject: string;
+    ref?: string;
+    verdict: string;
+    verdicts?: readonly string[];
+    reason: string;
+    criteria?: readonly string[];
+    domain: string;
+    by: string;
+    /** ISO time; defaults to now. */
+    decidedAt?: string;
+}
+/** A judgment input that cannot be recorded; the message names the field, never its value. */
+export declare class JudgmentInputError extends Error {
+    readonly name = "JudgmentInputError";
+}
+/** A verdict or criterion label: lowercase, spaces as `-`. */
+export declare function judgmentLabel(field: string, v: unknown, re?: RegExp): string;
+/** Checks and normalises `input` (labels lowercased, text trimmed). Throws `JudgmentInputError`. */
+export declare function normaliseJudgment(input: JudgmentInput, now: Date): JudgmentCore;
+/**
+ * An expert id as agent-facing text may show it: letters, digits and `. _ @ + -` kept, anything
+ * else `_`, at most 64 characters. Ids are checked on the way in; this is the second line.
+ */
+export declare function safeExpertId(by: string): string;
+/** The memory text recall shows for a judgment: who decided what, and why, in their words. */
+export declare function judgmentText(j: Judgment): string;
+/** True for a `judgment` memory that still counts: current, and not withdrawn. */
+export declare function isActiveJudgment(m: Memory, now: Date): m is Memory & {
+    judgment: Judgment;
+};
+/** Recorded by an agent over MCP and not confirmed by a person. */
+export declare function isUnconfirmedAgentJudgment(j: Pick<Judgment, 'via' | 'confirmed'>): boolean;
+/**
+ * The key a withdrawn, corrected or purged decision leaves behind: expert, domain, folded subject,
+ * folded reason and verdict, hashed. It leaves out `decidedAt` (a pack could shift it) and holds no
+ * text (a purged judgment keeps it).
+ */
+export declare function tombstoneKey(j: Pick<Judgment, 'by' | 'domain' | 'subject' | 'reason' | 'verdict'>): string;
+export interface RecordJudgmentDeps {
+    store: MemoryStore;
+    /** Where it is written: the grant's home node, unbound to any project. */
+    grant: Grant;
+    /** The acting principal's scope (its `agentId` is the author). */
+    scope: Scope;
+    /** Embeds the judgment for dense judging; without it judging is lexical. */
+    embed?: Embedder;
+    now?: Date;
+    /** The harness or tool that recorded it, for `source`. */
+    harness?: string;
+}
+export interface RecordJudgmentResult {
+    /**
+     * `added`: a new judgment. `corrected`: it replaced an earlier judgment of the same item by the
+     * same expert, recorded the same way (by a person, or by an agent). `unchanged`: that earlier
+     * judgment already says this.
+     */
+    outcome: 'added' | 'corrected' | 'unchanged';
+    memory: Memory;
+    /** The judgment it replaced (`corrected`). */
+    supersedes?: string;
+    /** Kinds of secret redacted from the text. */
+    redacted: string[];
+    /** The embedder failed: the judgment is kept, lexical-only. */
+    embedFailed?: true;
+}
+/**
+ * Records one judgment. When the same expert already judged the same item (same `ref` and domain)
+ * and it was recorded the same way (by a person, or by an agent over MCP), the new judgment
+ * corrects the old one (kept, retracted, linked both ways), unless it says the same thing. An
+ * agent-recorded judgment never corrects a person's: it is recorded alongside. Throws
+ * `JudgmentInputError` for bad input.
+ */
+export declare function recordJudgment(input: JudgmentInput, deps: RecordJudgmentDeps & {
+    via: JudgmentVia;
+    pack?: JudgmentPackOrigin;
+    corrects?: Memory;
+}): Promise<RecordJudgmentResult>;
+export interface ImportJudgmentsResult {
+    added: number;
+    corrected: number;
+    /** Already recorded with the same decision. */
+    unchanged: number;
+    /** The same decision was withdrawn, corrected or purged here: not brought back. */
+    tombstoned: number;
+    /** Rows a secret was redacted from. */
+    redacted: number;
+    /** Rows the embedder failed on (kept, lexical-only). */
+    embedFailed: number;
+}
+/**
+ * Records many judgments (a bulk import of past decisions), reading the store once and embedding
+ * in batches. Every row is checked before anything is written, and more than
+ * `JUDGMENT_LIMITS.importRows` is refused. A row matching a decision withdrawn, corrected or purged
+ * here is skipped and counted (`tombstoned`).
+ */
+export declare function importJudgments(rows: readonly JudgmentInput[], deps: RecordJudgmentDeps & {
+    via?: 'import' | 'sdk';
+}): Promise<ImportJudgmentsResult>;
+/**
+ * Withdraws a judgment: it is marked withdrawn (by which operator, when), retracted and its
+ * validity closed, so judging, recall (every time mode), export and packs stop using it at once,
+ * and its tombstone keeps imports from bringing it back. The record stays for
+ * `oort judge list --all`; `purgeJudgment` removes its text. Returns false when it was already
+ * withdrawn or is not a judgment.
+ */
+export declare function withdrawJudgment(store: MemoryStore, grant: Grant, m: Memory, by: string, now?: Date): Promise<boolean>;
+/**
+ * Confirms an agent-recorded (`mcp`) judgment: a person (`by`, the operator) vouches that the
+ * expert really decided it, and judging uses it from then on. Only for a current, unconfirmed
+ * agent-recorded judgment; returns false otherwise. Never offered over MCP.
+ */
+export declare function confirmJudgment(store: MemoryStore, grant: Grant, m: Memory, by: string, now?: Date): Promise<boolean>;
+/**
+ * Purges a judgment's text: withdraws it if it is not already, keeps its tombstone, and blanks
+ * the subject, ref, reason, criteria, memory text and embedding. What is left is an audit stub:
+ * the expert, domain, verdict, times, who withdrew and purged it, and the tombstone. Returns false
+ * when it was already purged or is not a judgment.
+ */
+export declare function purgeJudgment(store: MemoryStore, grant: Grant, m: Memory, by: string, now?: Date): Promise<boolean>;
+/** The item to judge. */
+export interface JudgeItem {
+    summary: string;
+    details?: string;
+    ref?: string;
+    /** Only precedents of this domain count. */
+    domain?: string;
+    /** Only this expert's precedents count. */
+    by?: string;
+}
+export interface JudgeOptions {
+    /** How many precedents to use. Default 5. */
+    k?: number;
+    /** The probability a prediction needs; below it the answer is "needs the expert". Default 0.7. */
+    threshold?: number;
+    /** The similarity a precedent needs to count as near. Default 0.45 (dense) or 0.25 (lexical). */
+    minSimilarity?: number;
+    /** The share of the near precedents' weight one verdict needs; below it they disagree. Default 0.6. */
+    minAgreement?: number;
+    /**
+     * Also use judgments imported from packs. Default false: a pack's experts are whoever its
+     * exporter says they are, so only judgments made here count unless the caller asks.
+     */
+    includeImported?: boolean;
+    /**
+     * Also use agent-recorded judgments nobody confirmed. Default false: an agent could have
+     * recorded anything in an expert's name.
+     */
+    includeAgentRecorded?: boolean;
+    /** Leave these out (evaluation: an item never counts as its own precedent). */
+    exclude?: (m: Memory & {
+        judgment: Judgment;
+    }) => boolean;
+}
+export declare const JUDGE_DEFAULTS: Readonly<{
+    k: 5;
+    threshold: 0.7;
+    minSimilarityDense: 0.45;
+    minSimilarityLexical: 0.25;
+    minAgreement: 0.6;
+    /** A suggestion needs at least this many near precedents agreeing with it. */
+    minAgreeing: 2;
+}>;
+export interface JudgeDeps {
+    store: MemoryStore;
+    grant: Grant;
+    embed?: Embedder;
+    /** Its `judge` makes the prediction; without it judging returns precedents only. */
+    decide?: Pick<DecisionController, 'judge'>;
+    now?: Date;
+}
+/** One precedent as a judging result cites it. */
+export interface Precedent {
+    id: string;
+    subject: JudgmentSubject;
+    verdict: string;
+    reason: string;
+    criteria: string[];
+    domain: string;
+    by: string;
+    decidedAt: string;
+    similarity: number;
+    /** At least `minSimilarity`: it counted. */
+    near: boolean;
+    /** Its verdict is the predicted one. */
+    agrees?: boolean;
+    /** How it was recorded (`mcp`: by an agent). */
+    via: JudgmentVia;
+    /** A person recorded it, or confirmed an agent's record of it. */
+    confirmed: boolean;
+    /** Imported from this pack: its expert is as the pack's exporter states it. */
+    pack?: {
+        id: string;
+        name: string;
+    };
+    imported?: true;
+}
+/**
+ * Why the answer is not a confident prediction:
+ * `no-precedents` (nothing recorded for this domain or expert), `too-far` (nothing close enough),
+ * `too-few` (fewer than two near precedents agree with the answer), `precedents-disagree` (the
+ * near precedents split), `low-confidence` (the prediction is below the threshold), `no-decider`
+ * (no Jev key: precedents only), `decider-failed` (the call failed).
+ */
+export type JudgeWhy = 'no-precedents' | 'too-far' | 'too-few' | 'precedents-disagree' | 'low-confidence' | 'no-decider' | 'decider-failed';
+export interface JudgeResult {
+    /**
+     * `suggested`: a prediction at or above the threshold that at least two near precedents agree
+     * with. `needs-expert`: no prediction can be trusted (see `why`). `precedents-only`: no decider,
+     * so here are the precedents, no verdict.
+     */
+    status: 'suggested' | 'needs-expert' | 'precedents-only';
+    why?: JudgeWhy;
+    /**
+     * A prediction, never the expert's decision: present with `suggested`, and as a lean with
+     * `low-confidence` and `too-few`.
+     */
+    prediction?: {
+        verdict: string;
+        probability: number;
+        probabilities: Record<string, number>;
+    };
+    /** The precedents used (near ones), or the nearest ones when none is near. Nearest first. */
+    precedents: Precedent[];
+    /** The verdicts offered to the decider: those the near precedents voted for. */
+    verdicts: string[];
+    /** The near precedents' verdicts, weighted by similarity, as shares. */
+    agreement: Record<string, number>;
+    similarity: 'dense' | 'lexical';
+    threshold: number;
+    minSimilarity: number;
+    degraded?: ('embed-failed' | 'decider-failed')[];
+    decisions: Decision[];
+    /** Imported judgments that matched the filters but were left out (`includeImported` false). */
+    importedExcluded?: number;
+    /** Unconfirmed agent-recorded judgments left out (`includeAgentRecorded` false). */
+    agentRecordedExcluded?: number;
+}
+/**
+ * The active judgments of `filter`'s domain and expert (when it names them). Judgments imported
+ * from packs only with `includeImported`, unconfirmed agent-recorded ones only with
+ * `includeAgentRecorded`.
+ */
+export declare function activeJudgments(store: MemoryStore, grant: Grant, filter: {
+    domain?: string;
+    by?: string;
+    includeImported?: boolean;
+    includeAgentRecorded?: boolean;
+}, now: Date, embeddings?: boolean): Promise<(Memory & {
+    judgment: Judgment;
+})[]>;
+/**
+ * Applies the expert's judgments to `item`: finds the nearest active precedents (domain- and
+ * expert-filtered), then asks the decider for a choice over the verdicts they voted for, with the
+ * precedents and their reasons as state. It answers "needs the expert" instead of guessing when
+ * there are no precedents, none is near, fewer than two near precedents would back the answer,
+ * the near ones disagree, or the prediction is below `threshold`; and returns precedents only
+ * when there is no decider. Never writes anything.
+ */
+export declare function judge(item: JudgeItem, deps: JudgeDeps, opts?: JudgeOptions): Promise<JudgeResult>;
+export declare const JUDGMENT_PACK_VERSION = 1;
+/** The first line of a pack. */
+export interface JudgmentPackManifest {
+    oort: 'judgment-pack';
+    version: 1;
+    name: string;
+    exportedAt: string;
+    /** The agent that exported it. */
+    exportedBy: string;
+    count: number;
+    /**
+     * sha256 over the manifest's metadata (version, name, exportedAt, exportedBy) and the judgment
+     * lines, as `packDigest` computes it. Its first 16 hex characters are the pack's id.
+     */
+    digest: string;
+    /** The domains and experts inside. A reader checks them against the lines (they must match). */
+    domains: string[];
+    experts: string[];
+}
+/** One judgment in a pack: the decision and its id, without vectors or local state. */
+export interface JudgmentPackLine {
+    id: string;
+    judgment: Omit<Judgment, 'withdrawn' | 'via' | 'pack'> & {
+        via: JudgmentVia;
+        /**
+         * Where the exporter got it, when it was itself imported: the exporter's own record, which a
+         * reader keeps only as an untrusted claim (`claimedEarlier`).
+         */
+        pack?: Omit<JudgmentPackOrigin, 'claimedEarlier'>;
+    };
+}
+/** Raised for a file that is not a readable judgment pack. */
+export declare class JudgmentPackError extends Error {
+    readonly name = "JudgmentPackError";
+}
+/** Length caps for pack metadata. */
+export declare const PACK_LIMITS: Readonly<{
+    name: 120;
+    exportedBy: 128;
+    id: 128;
+    time: 40;
+}>;
+/** What the digest binds besides the lines. */
+export interface PackMeta {
+    name: string;
+    exportedAt: string;
+    exportedBy: string;
+}
+/**
+ * The digest of a pack: hex sha256 over its metadata (version, name, exportedAt, exportedBy, as a
+ * JSON array) and then each judgment line as written. Changing the name, the exporter, the time or
+ * any line changes it.
+ */
+export declare function packDigest(meta: PackMeta, lines: readonly string[]): string;
+/**
+ * A pack of `judgments` (active ones only; withdrawn and corrected ones never travel), as JSON
+ * Lines: a manifest, then one line per judgment in id order. Attribution (`by`, `decidedAt`)
+ * travels with each judgment; embeddings do not (the importer embeds them with its own model).
+ */
+export declare function formatJudgmentPack(judgments: readonly Memory[], meta: {
+    name: string;
+    exportedBy: string;
+    exportedAt: Date;
+}, now?: Date): string;
+export interface ParsedJudgmentPack {
+    manifest: JudgmentPackManifest;
+    lines: JudgmentPackLine[];
+}
+/**
+ * Reads a pack and checks everything a person is shown before importing it: the manifest's
+ * metadata (plain text, length caps), the count, the digest over the metadata and the lines, every
+ * judgment as `recordJudgment` would check it, any claimed earlier origin (exact shape), and that
+ * the manifest's domains and experts are exactly those of the lines. The lines come back rebuilt
+ * from their checked fields only. The digest proves integrity, not authorship: a pack is as
+ * trustworthy as whoever handed it over. Throws `JudgmentPackError`.
+ */
+export declare function parseJudgmentPack(textIn: string): ParsedJudgmentPack;
+/** A pack line's judgment as recording input. */
+export declare function packInput(j: JudgmentPackLine['judgment']): JudgmentInput;
+export interface ImportPackResult {
+    added: string[];
+    /**
+     * Line ids not added because they are already here: imported from this very pack before (same
+     * digest and line id), or the same exact decision is in the store, from any origin.
+     */
+    skipped: string[];
+    /**
+     * Line ids whose decision was withdrawn, corrected or purged here (matched by its tombstone,
+     * whatever `decidedAt` the pack gives it): never brought back.
+     */
+    tombstoned: string[];
+}
+/**
+ * Imports a parsed pack into the grant's home node, reading the store once and embedding in
+ * batches. Each judgment keeps its expert and decision time, and records where it came from:
+ * `judgment.pack`, built only from this pack (its digest id, the digest-bound name, exporter and
+ * time, and the line's id). An earlier origin the line claims is kept apart as `claimedEarlier`,
+ * marked untrusted, and used for nothing.
+ *
+ * A line is skipped when this pack was imported before (same digest and line id) or the same
+ * exact decision is already here, and reported as tombstoned when its decision was withdrawn,
+ * corrected or purged here: a pack never brings back what an expert took back.
+ */
+export declare function importJudgmentPack(pack: ParsedJudgmentPack, deps: RecordJudgmentDeps): Promise<ImportPackResult>;
+/** Rows of a CSV file (RFC 4180: quoted fields, `""` for a quote, newlines inside quotes). */
+export declare function parseCsv(input: string): string[][];
+/**
+ * Past decisions from a CSV file (a header row naming the columns: subject, verdict, reason,
+ * domain, by, and optionally ref, criteria and verdicts as `;`-separated lists, decided_at) or JSON
+ * Lines (one object per line with the same keys; lists may be arrays). `defaults` fills a missing
+ * domain or expert. More than `JUDGMENT_LIMITS.importRows` rows is refused. Each row is checked as
+ * `recordJudgment` checks it; the first bad row throws `JudgmentInputError` naming its line.
+ */
+export declare function parseJudgmentRows(text: string, format: 'csv' | 'jsonl', defaults?: {
+    domain?: string;
+    by?: string;
+}): JudgmentInput[];
+export declare const EVAL_THRESHOLDS: readonly number[];
+/** One threshold's numbers: how much is predicted, and how often the prediction is the expert's. */
+export interface EvalPoint {
+    threshold: number;
+    /** Items predicted at or above the threshold, as a share of all items. */
+    coverage: number;
+    /** Of those, the share whose prediction matched the expert's verdict; null when none. */
+    agreement: number | null;
+    predicted: number;
+    agreed: number;
+}
+export interface EvalReport {
+    /** Per domain, then `(all)` (not a valid domain label, so it never collides). */
+    domains: Record<string, {
+        items: number;
+        points: EvalPoint[];
+        why: Partial<Record<JudgeWhy, number>>;
+    }>;
+    thresholds: number[];
+    similarity: 'dense' | 'lexical' | 'mixed';
+}
+/**
+ * Judges each held-out decision against the store (never recording it, and never using the item
+ * itself as a precedent: leave-one-out by item ref and by exact decision) and compares the
+ * prediction with the expert's verdict: agreement and coverage per domain at each threshold.
+ * An item counts as predicted at threshold t when judging would say `suggested` with t as the
+ * threshold. Needs a decider; without one nothing is ever predicted.
+ */
+export declare function evaluateJudgments(heldOut: readonly JudgmentInput[], deps: JudgeDeps, opts?: Omit<JudgeOptions, 'threshold'> & {
+    thresholds?: readonly number[];
+}): Promise<EvalReport>;