@avantf/dsh-mem 0.3.0 → 0.4.0

package/lib/engine/mem/git.d.ts

@@ -0,0 +1,73 @@
+import type { AvantfLogger } from '../mem-contract/index.js';
+/**
+ * A reusable git wrapper for the stores' on-disk artifacts.
+ *
+ * It is deliberately root-agnostic: the knowledge corpus (`knowledge.docs.dir`, the default root)
+ * is one use, and "share a whole store" is another — point `root` at `~/.avantf/knowledge` or
+ * `~/.avantf` and pass an `ignore` list so the databases stay out of the history. The caller owns
+ * WHAT is versioned; this owns HOW, and nothing else in the codebase needs to know git exists.
+ *
+ * THREE PROPERTIES ARE LOAD-BEARING, and they are why this is not just `execFileSync` at each
+ * call site:
+ *
+ *  - **It never throws.** Every caller writes here AFTER its real mission is durable (the row is
+ *    committed, the document is indexed). A missing `git`, a locked index, or an unwritable repo
+ *    must not turn a successful operation into a failed one — so failures are warned and swallowed,
+ *    the same rule `IngestResult.file_error` follows for the managed file itself.
+ *  - **It is always recognisable as automatic, and never invents an identity.** Every commit
+ *    carries the `Automatic: avantf-mem` trailer. When the machine has an identity the commit is
+ *    authored with it (the repo is the user's, and they may commit in it by hand — attributing
+ *    their machine's mission to a bot by default would be the wrong kind of surprise); when it has
+ *    NONE, the repo gets a LOCAL bot identity rather than failing or writing to the user's GLOBAL
+ *    config, which is what lets the commit happen at all.
+ *  - **It never commits an empty change.** `git status --porcelain` gates the commit, because
+ *    `git add` + `git commit` with nothing staged fails, and a store write that changed nothing
+ *    (a re-ingest of identical text) is common.
+ */
+type GitMode = 'auto' | 'off';
+interface GitRepoOptions {
+    /** The directory this repo tracks. `init`/`commit` no-op when it does not exist. */
+    root: string;
+    /** `auto` (default) = create the repo on first commit; `off` = never invoke git at all. */
+    mode?: GitMode;
+    /**
+     * Patterns written to `.gitignore` when the repo is CREATED. An existing `.gitignore` is left
+     * alone. Only matters when `root` is broader than a text directory — e.g. pointing at a store
+     * directory brings the SQLite files with it, and those must never enter the history.
+     */
+    ignore?: readonly string[];
+    /** Committer used when the machine has no identity. Defaults to the avantf bot. */
+    identity?: {
+        name: string;
+        email: string;
+    };
+    logger?: AvantfLogger;
+    timeoutMs?: number;
+}
+export declare class GitRepo {
+    readonly root: string;
+    private readonly mode;
+    private readonly ignore;
+    private readonly identity;
+    private readonly logger?;
+    private readonly timeoutMs;
+    constructor(options: GitRepoOptions);
+    /** Whether git is in play at all (a disabled repo does nothing, silently and by design). */
+    get enabled(): boolean;
+    /**
+     * Create the repository if it is not one yet (writing `.gitignore` when it does). Idempotent and
+     * never throws; returns whether a repository exists afterwards.
+     */
+    init(): boolean;
+    /** Stage and commit whatever changed under `root`. No-op when nothing did. Never throws. */
+    commit(message: string): void;
+    /** Commit subjects, newest first. `[]` when git is off, absent, or the repo has no commits. */
+    history(limit?: number): string[];
+    /** Current branch, or `null` when unavailable (never throws — this is diagnostics only). */
+    branch(): string | null;
+    private ensureIdentity;
+    private writeIgnore;
+    private warn;
+    private git;
+}
+export {};

package/lib/engine/mem/hrr/algebra.d.ts

@@ -0,0 +1,30 @@
+export declare class ShapeMismatchError extends Error {
+}
+/** bind(a, b) = (a + b) mod 2π — compose two phase vectors. */
+export declare function bind(a: Float64Array, b: Float64Array): Float64Array;
+/** bundle(*vectors) — circular-mean superposition `angle(Σ exp(i·v)) mod 2π`. */
+export declare function bundle(...vectors: Float64Array[]): Float64Array;
+/**
+ * Cosine-like phase similarity in [0, 1]: `(sum cos(a-b) + dim) / (2*dim)`.
+ *
+ * THE BASELINE IS 0.5, AND THAT SHAPES HOW THE LEG CONTRIBUTES. Two unrelated random bundles score
+ * 0.5 in expectation, and at dim=1024 the spread around it is tiny — measured over 200 unrelated
+ * pairs against five different probes: mean 0.499–0.503, sd 0.0105–0.0111, and the BEST of the 200
+ * reached only 0.525–0.536. A bundle scores 1.0 against itself, so the range that matters in
+ * practice is [~0.5, 1.0].
+ *
+ * Consequence at the fusion step: `scaleByMax` divides the leg by its own maximum, so the weakest
+ * unrelated candidate still keeps 0.88–0.90 of the strongest one's contribution. Within a set of
+ * candidates that do NOT share the probe's entities, this leg is therefore close to a CONSTANT boost
+ * rather than a ranking signal — which is benign in `MemoryStore.hrrPath`'s normal path (every
+ * candidate there shares an entity by construction, and sharing moves the score well above 0.5) and
+ * NOT benign in its fallback path, where the scored set is "the `cap` most recent facts" and most of
+ * them share nothing.
+ *
+ * Stated rather than fixed: subtracting the baseline (`max(0, (sim - 0.5) * 2)`) would make the leg
+ * discriminative, but it changes ranking, and the differential that would justify it is the same one
+ * `docs/PROVENANCE_REVIEW.md` N5 records as missing — the frozen eval set exercises `recall.search`,
+ * and this leg only runs for `recall.probe`, so no existing gate would move either way. Pinned by
+ * `test/hrr.spec.ts` so the change has to be made deliberately, with a probe-shaped eval beside it.
+ */
+export declare function phaseSimilarity(a: Float64Array, b: Float64Array): number;

package/lib/engine/mem/hrr/atoms.d.ts

@@ -0,0 +1,22 @@
+/** 2π (float64, cross-platform stable). */
+export declare const TWO_PI: number;
+export declare class AtomDimensionError extends Error {
+}
+/**
+ * Deterministic phase vector derived from `name` (Plate-style HRR atom).
+ * SHA-256(name) → rolling SHA-256 blocks → uint64 LE → phase in [0, 2π).
+ * Same (name, dim) yields identical vectors across environments.
+ *
+ * The returned array is SHARED with the memo (treat it as immutable — callers only read it).
+ */
+export declare function atom(name: string, dim?: number): Float64Array;
+/** Batch-derive atom vectors; returns `names.length` rows of dim. */
+export declare function atomBatch(names: string[], dim?: number): Float64Array[];
+/**
+ * Whether `vec` is a valid phase vector (Float64Array, even positive length, finite and in [0, 2π)).
+ *
+ * The finiteness check is not redundant with the range check: every comparison against NaN is false,
+ * so `NaN < 0 || NaN >= TWO_PI` passes and a corrupt blob decoded to NaN used to read as a valid
+ * atom — then `phaseSimilarity` returned NaN and poisoned the fused ranking (see `scaleByMax`).
+ */
+export declare function isValidAtom(vec: Float64Array): boolean;

package/lib/engine/mem/hrr/encode.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Encode a fact's entity set as an HRR phase vector (composition via bundle of
+ * entity atoms). Deterministic for a given entity set, enabling the HRR probe
+ * (phase similarity) used for entity-level recall of facts whose entities were
+ * not captured by the entity table.
+ */
+export declare function encodeHrrEntityVector(entityNames: string[], dim?: number): Float64Array;
+/**
+ * Serialize a phase vector to bytes (for SQLite BLOB).
+ *
+ * Written as explicit little-endian, matching `float32ToBytes` — the layout is then
+ * a property of the format rather than of the host's byte order.
+ */
+export declare function hrrToBytes(vec: Float64Array): Buffer;
+/**
+ * Deserialize bytes to a phase vector, or `null` when the bytes are not one.
+ *
+ * Reads through a `DataView` instead of `new Float64Array(buf.buffer, buf.byteOffset, …)`:
+ * that constructor requires an 8-byte-ALIGNED `byteOffset`, and nothing about a SQLite
+ * BLOB promises one (the driver happens to hand back offset-0 views today, and the adapter passes
+ * that offset through unchanged, but the
+ * callers here also pass plain `Uint8Array`s — a subarray or a pooled `Buffer` slice
+ * would throw a RangeError from deep inside retrieval). A trailing partial element is
+ * ignored, as before.
+ *
+ * A NON-FINITE phase is rejected here rather than scored: every range check in
+ * {@link isValidAtom} compares false against NaN, so a corrupt blob would otherwise sail through
+ * the caller's length check, make `phaseSimilarity` return NaN, and poison the whole fused ranking
+ * (one NaN in a sort comparator leaves the ORDER undefined, not just one score wrong). Callers
+ * already treat `null` as "skip this row".
+ */
+export declare function hrrFromBytes(buf: Buffer | Uint8Array): Float64Array | null;

package/lib/engine/mem/hrr/index.d.ts

@@ -0,0 +1,3 @@
+export * from './atoms.js';
+export * from './algebra.js';
+export * from './encode.js';

package/lib/engine/mem/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The engine's public surface.
+ *
+ * Deliberately narrow, and deliberately explicit about what is NOT here. This used to be `export *`
+ * over twenty modules, which published the database connection and schema, the migration list, the
+ * HRR algebra, the entity extractor, the eval runner and the git wrapper to every consumer — none of
+ * which any consumer used (the DSH plugin, the MCP server and the CLI import ten symbols between
+ * them). A wide surface is not a harmless convenience: anything exported is a promise, and the
+ * internals move (a DAO signature, a migration step, a tokenizer convention) on the assumption that
+ * only the stores call them.
+ *
+ * Everything else is still importable BY MODULE PATH, which is what this package's own specs and the
+ * `scripts/bench-*.mjs` benchmarks do — reaching into the engine is a choice a caller has to spell
+ * out, rather than something the front door hands them.
+ */
+export * from './config/paths.js';
+export * from './config/loader.js';
+export * from './modelBootstrap.js';
+export * from './dispatch.js';
+export * from './runtime.js';
+export * from './store/memory.js';
+export * from './store/knowledge.js';
+export * from './store/hybrid.js';
+export * from './store/source_picker.js';
+export * from './store/lexical.js';
+export * from './store/floors.js';
+export { registerSemanticBackend, registerReranker, registerVectorStore, type Reranker, type SemanticBackend, type VectorStore, } from '../mem-retrieval/index.js';

package/lib/engine/mem/lifecycle/contradiction.d.ts

@@ -0,0 +1,156 @@
+import { MAX_REPORTED_CONFLICTS, type ContradictionRecord } from '../../mem-contract/index.js';
+import type { Db } from '../db/conn.js';
+import { type ConflictPair, type StoredConflict } from '../db/dao/contradictions.js';
+export { polarityLookupSql, sameSubjPredLookupSql } from '../db/dao/triples.js';
+/** Re-exported for `@avantf/mem` consumers; the value lives in the contract (the tool description states it). */
+export { MAX_REPORTED_CONFLICTS };
+/**
+ * Embedding-fallback contradiction score: `entity_overlap * semantic_sim`, only
+ * when all hold: min entity count, entity overlap floor, and cos sim in
+ * [sim_min, sim_dup_max]. `sim > sim_dup_max` is a near-duplicate → 0.
+ * Returns [0,1]; 0 means "not a contradiction candidate".
+ */
+export declare function detectContradictionEmbedding(entitiesA: Iterable<string>, entitiesB: Iterable<string>, vecA: Float32Array, vecB: Float32Array, opts?: {
+    minEntities?: number;
+    overlapMin?: number;
+    simMin?: number;
+    simDupMax?: number;
+}): number;
+interface ContradictionSig {
+    fact_a: number;
+    fact_b: number;
+    score: number;
+}
+/**
+ * What one detection pass could and could not do.
+ *
+ * `logged` alone is not enough to decide whether a fact's check is FINISHED: it says "no pair was
+ * recorded", which is also the answer for a fact whose embedding leg never ran because its vector
+ * was not in the live index (another space, another process's write, dropped while the index was
+ * rebuilt). Stamping `conflict_checked` on that answer is a permanent, silent exemption — the very
+ * failure the durable queue exists to prevent. So the pass reports the two separately.
+ */
+export interface CheckResult {
+    /** Pairs this pass inserted (`maybeLog` skips the ones already open). */
+    logged: Sig[];
+    /**
+     * Facts whose EMBEDDING leg is COMPLETE — a vector was available for them, so nothing about
+     * their check depends on a later run. The store stamps exactly these; anything absent stays
+     * queued and `conflict_pending` keeps reporting it.
+     */
+    complete: number[];
+}
+/**
+ * Contradiction detector: the structural signals (always, no vectors) then the embedding
+ * fallback when vectors are available. Pairs are normalized (min,max) and deduped.
+ *
+ * STATELESS about what is pending. It used to hold a Set of changed fact ids and retry them, which
+ * meant "awaiting the embedder" was lost on every restart, could grow without bound, and needed a
+ * bound plus a dropped-count to stay honest. `facts.conflict_checked` now records it durably, so
+ * this class only ever answers "what do these facts conflict with" (`checkOne` / `checkMany`) and
+ * the STORE owns the queue (see `MemoryStore.checkContradictions`).
+ */
+export declare class ContradictDetector {
+    private readonly db;
+    private readonly threshold;
+    private readonly fetchVectors;
+    private readonly fetchEntities;
+    /** Optional batched entity fetch — one query for the whole candidate set instead of N+1. */
+    private readonly fetchEntitiesBatch?;
+    private readonly triples;
+    private readonly repo;
+    private readonly entities;
+    private readonly facts;
+    constructor(db: Db, threshold?: number, fetchVectors?: (ids: number[]) => Map<number, Float32Array>, fetchEntities?: (id: number) => string[], 
+    /** Optional batched entity fetch — one query for the whole candidate set instead of N+1. */
+    fetchEntitiesBatch?: ((ids: number[]) => Map<number, string[]>) | undefined);
+    /**
+     * Check ONE fact against the corpus — the WRITE-path entry.
+     *
+     * A fact is checked as it is written, so the open-contradiction list is truthful
+     * without anyone remembering to run a sweep (the UI used to read an always-empty
+     * log as "no contradictions").
+     *
+     * It leaves the pending set itself (see {@link detect}): the id stays queued only while
+     * the embedding leg could not run — i.e. no vector in the live index — so a later
+     * {@link checkMany} can retry exactly those. Re-checking a fact that was already scored
+     * with its vector would repeat an identical pass, and doing that for every write is what
+     * made the queue grow without bound.
+     */
+    checkOne(factId: number): CheckResult;
+    /**
+     * A fact left the active corpus: retire the open conflicts that name it (see
+     * {@link ContradictionsDao.resolveForFact}). Returns how many rows were closed.
+     */
+    resolveForFact(factId: number): number;
+    /**
+     * The lifecycle tick's bulk form: close the open conflicts of every id in one pass.
+     *
+     * The per-id loop cost O(archived × log) — measured 6.3 s for 999 ids at 99k open pairs, inside
+     * the tick's single IMMEDIATE transaction, i.e. holding the write lock for that whole time.
+     */
+    resolveForFacts(factIds: readonly number[]): number;
+    /** Every OPEN conflict naming `factId` — what a writer is told about (see the repo). */
+    openConflictsFor(factId: number): ConflictPair[];
+    /** One stored conflict by id (adjudication needs the pair and its state). */
+    get(id: number): StoredConflict | undefined;
+    /** Record a verdict on a conflict WITHOUT touching the facts (see `resolveContradiction`). */
+    resolve(id: number, resolution: 'true_positive' | 'false_positive', loserFactId?: number): void;
+    /** List conflicts for the admin surface (`resolved` 0 = open). */
+    list(resolved?: number, category?: string, threshold?: number, limit?: number): ContradictionRecord[];
+    /** Drain the pending set: the incremental sweep (`admin contradict_check`). */
+    /**
+     * Check a LIST of facts — the store's durable drain supplies it (`contradict_check`).
+     *
+     * Only ACTIVE ids participate (design: 新变更 × 全量 active). A fact that is no longer active
+     * can never be checked again — its open rows were retired when it left the corpus — so it is
+     * filtered out here. It needs no stamp either: the queue predicate is `status = 'active'`.
+     */
+    checkMany(factIds: readonly number[]): CheckResult;
+    /**
+     * Both signal families over the given (already filtered to ACTIVE) facts.
+     *
+     * `suppressed` decides how the already-logged set is read: a single-fact check only needs that
+     * fact's pairs, while the sweep reads the whole log once. Both are correct because `maybeLog` is
+     * only ever called with one side being a CHANGED id.
+     */
+    private detect;
+    /** Structural signals — pure SQL, no vectors needed. */
+    private structuralPass;
+    /** ACTIVE subset of `ids` (batched: the pending set grows with the corpus). */
+    private filterActive;
+    /**
+     * Active facts that could POSSIBLY conflict with `factId` through the embedding leg.
+     *
+     * The scorer is `overlap × cosine` with `overlap = |A∩B| / |A∪B|`, gated by
+     * `overlap ≥ EMBED_OVERLAP_MIN`, `sim ≤ EMBED_SIM_DUP_MAX` and `|·| ≥ EMBED_MIN_ENTITIES`,
+     * and the pair is only logged when the score reaches `threshold`. So a qualifying pair
+     * must have
+     *
+     *     p := max(EMBED_OVERLAP_MIN, threshold / EMBED_SIM_DUP_MAX)   (score ≤ overlap × simDupMax)
+     *     |A∩B| ≥ p·|A|      because |A∪B| ≥ |A|
+     *     |B|   ≤ |A|/p      because |A∩B| ≤ |A| and |A∩B| ≥ p·|B|
+     *
+     * Both are NECESSARY conditions, so filtering on them drops no pair that could ever be
+     * logged — it only shrinks the set the vector fetch and the pairwise cosine then pay for.
+     * On a hub entity (one entity shared by 30k facts, checked fact has two) the shared-entity
+     * floor alone removes the whole hub, because 1 shared entity cannot reach `p·|A| = 2`.
+     */
+    private findEntitySharing;
+    /**
+     * Score every changed fact against its candidate set.
+     *
+     * Returns the ids whose OWN vector this pass had in hand — the embedding leg RAN for those, so
+     * they are the only ones whose check is complete. Note what this is NOT: `logged.length`. A
+     * fact can be fully checked and log nothing (no candidate reached the threshold), and a fact
+     * whose vector is missing was never checked at all yet logs nothing either. Only the vector
+     * table separates the two, which is why the pass returns it instead of the caller re-deriving
+     * it from the database (`semantic_vector IS NOT NULL` is a different question — see `CheckResult`).
+     *
+     * The entity floor counts as complete: `detectContradictionEmbedding` returns 0 below
+     * `EMBED_MIN_ENTITIES` whatever the vectors are, so no later pass could score differently.
+     */
+    private embeddingPass;
+    private maybeLog;
+}
+export type Sig = ContradictionSig;

package/lib/engine/mem/lifecycle/index.d.ts

@@ -0,0 +1,5 @@
+export * from './contradiction.js';
+export * from './maintenance.js';
+export * from './trust.js';
+export * from './presence.js';
+export * from './tick.js';

package/lib/engine/mem/lifecycle/maintenance.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The manual `admin maintenance` entry — now a thin shell over the automatic tick
+ * (spec docs/TRUST_MODEL.md §6.1 / M3b).
+ *
+ * Surface stability (D10): the original report keys are all preserved
+ * (`decayed / archived_ttl / archived_age / purged / purged_ids / archived_ids`)
+ * and the new detail is purely additive. `archived_age` now means "non-TTL
+ * automatic archival" = `forgot + idle`.
+ *
+ * The `maintenance` action forces a FULL pass (no settle budget); the automatic
+ * startup/heartbeat passes use `tick_max_facts`.
+ */
+import type { Config } from '../../mem-contract/index.js';
+import type { Db } from '../db/conn.js';
+export interface MaintenanceResult {
+    /** Rows whose trust was materialized by the settle sweep (see tick.ts). */
+    decayed: number;
+    archived_ttl: number;
+    /** Non-TTL automatic archival = `forgot + idle` (kept name, widened meaning). */
+    archived_age: number;
+    purged: number;
+    /** Fact ids physically deleted by the purge — callers evict their vectors from the live index. */
+    purged_ids: number[];
+    /** Fact ids archived by this pass — the live index tracks ACTIVE facts only. */
+    archived_ids: number[];
+    settled: number;
+    clock: number;
+    archived_forgot: number;
+    archived_idle: number;
+    /** Rows still pending settle because the budget ran out (always 0 for a forced pass). */
+    skipped: number;
+    /** Rows still due for TTL/forgot/idle because the budget ran out (0 for a forced pass). */
+    archived_deferred: number;
+    /** Rows still due for purge when the budget ran out (0 for a forced pass). */
+    purged_deferred: number;
+}
+/**
+ * Run one lifecycle pass now.
+ *
+ * @param db - memory DB.
+ * @param cfg - resolved config.
+ * @param opts.clock - active-day clock to settle at (defaults to the stored clock).
+ * @param opts.budget - settle budget; `0` (default here) = full pass.
+ */
+export declare function runMaintenance(db: Db, cfg: Config, opts?: {
+    clock?: number;
+    budget?: number | null;
+}): MaintenanceResult;

package/lib/engine/mem/lifecycle/presence.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The ACTIVE-DAY clock (spec docs/TRUST_MODEL.md §2.1).
+ *
+ * `clock` counts days the system was actually present (startup + heartbeat), with
+ * each presence contributing at most `presence.gap_cap_days` days — so a 90-day
+ * shutdown ages memories by 1 day, while an always-on system advances 1:1 with the
+ * calendar. State lives in the existing `avantf_stats` key/value table.
+ *
+ * The read-modify-write runs inside an IMMEDIATE transaction: two processes starting
+ * together serialize, and the second one sees the fresh `last_seen` (gap ≈ 0), so
+ * the clock is never advanced twice.
+ */
+import type { Db } from '../db/conn.js';
+/** Current active-day count (0 when never initialized). */
+export declare function readClock(db: Db): number;
+/**
+ * Initialize/repair the clock. If the meta row was lost while facts exist, the
+ * clock must not trail their `settle_clock`, or those facts would never settle
+ * again (spec §2.1 self-heal).
+ */
+export declare function initClock(db: Db): number;
+/** Advance the clock for one presence; returns the new clock and what was counted. */
+export declare function advancePresence(db: Db, opts?: {
+    nowMs?: number;
+    gapCapDays?: number;
+}): {
+    clock: number;
+    counted: number;
+};

package/lib/engine/mem/lifecycle/tick.d.ts

@@ -0,0 +1,43 @@
+/**
+ * One trust/lifecycle tick (spec docs/TRUST_MODEL.md §4) — five ordered statements:
+ *
+ *   ① settle   — materialize decay for every row whose ACTIVE DAY changed
+ *   ② TTL      — calendar expiry (explicit instruction; pinned is not exempt)
+ *   ③ forgot   — trust ≤ forget_threshold after settling (pinned exempt)
+ *   ④ idle     — calendar fallback: unused for `idle_calendar_days`
+ *   ⑤ purge    — physical delete of archived rows past the window
+ *
+ * EVERY step is budgeted by the same `tick_max_facts`, not just ①.
+ *
+ * It used to say "only ① is budgeted; ②③④⑤ only ever touch critical rows", and that reading is
+ * wrong in the direction that matters: ②③④⑤ each run inside the tick's ONE `IMMEDIATE` transaction,
+ * which holds the write lock for its whole duration, so an unbounded archive or purge pass over a
+ * large corpus blocks every other process (and the startup path, which is where the tick runs) for
+ * as long as it takes. Bounding each step is what keeps that lock short; `archived_deferred` and
+ * `purged_deferred` report what a bounded pass left for the next beat, so a backlog is visible
+ * instead of silent. The whole pass is one transaction, and the archived/purged ids are returned so
+ * the caller can evict them from the live vector index.
+ */
+import type { Config } from '../../mem-contract/index.js';
+import type { Db } from '../db/conn.js';
+export interface TickResult {
+    clock: number;
+    /** Rows materialized by ① (equals "trust actually changed" — see the note in runTrustTick). */
+    settled: number;
+    archived_ttl: number;
+    archived_forgot: number;
+    archived_idle: number;
+    purged: number;
+    purged_ids: number[];
+    archived_ids: number[];
+    /** Rows still awaiting ① when the budget ran out (0 for a full pass). */
+    skipped: number;
+    /** Rows still due for ②③④ when the budget ran out (0 when the pass finished them). */
+    archived_deferred: number;
+    /** Rows still due for ⑤ when the budget ran out (0 when the pass finished them). */
+    purged_deferred: number;
+}
+export declare function runTrustTick(db: Db, cfg: Config, opts: {
+    clock: number;
+    budget?: number | null;
+}): TickResult;

package/lib/engine/mem/lifecycle/trust.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Trust & forgetting math — PURE functions, no DB and no clock of their own
+ * (`clock` / `nowMs` are always injected, so every rule is unit-testable).
+ *
+ * Spec: docs/TRUST_MODEL.md §2. Key rules encoded here:
+ *  - `eff = pinned ? 1 : clamp(trust − step × (clock − settle_clock), 0, 1)` (§2.2)
+ *  - recall only ever RAISES trust (`max(eff, …)`, R2) and never pins (D11)
+ *  - zero-gain recalls neither consume quota nor stamp `last_reinforced_at` (R10)
+ *  - explicit feedback can pin (snap to 1.0) or forget immediately (§2.4)
+ *  - `enabled=false` degrades `eff()` to the stored value (D12)
+ */
+import type { Config } from '../../mem-contract/index.js';
+export declare const DAY_MS = 86400000;
+/** Guard for "did the number actually move" comparisons. */
+export declare const EPSILON = 1e-9;
+type TrustConfig = Config['trust'];
+/** The facts-row subset the trust math needs. */
+export interface TrustRow {
+    trust_score: number;
+    settle_clock: number;
+    pinned: number | boolean;
+    bonus_count: number | null;
+    bonus_window_at: string | null;
+    status: string;
+}
+export declare function clamp01(v: number): number;
+export declare function isPinned(row: Pick<TrustRow, 'pinned'>): boolean;
+/**
+ * `'YYYY-MM-DD HH:MM:SS'` (SQLite UTC) or ISO → epoch ms; null/garbage → null.
+ *
+ * A stamp with NO zone designator is read as UTC, not as local time. `Date.parse` treats a zone-less
+ * ISO string as LOCAL, and everything in this store is written in UTC (`CURRENT_TIMESTAMP`, and
+ * {@link formatUtcTs}), so handing one over as-is would shift every quota window and every decay
+ * measurement by the host's UTC offset — a fact reinforced at 23:00 UTC+8 would look reinforced 8
+ * hours earlier, and the 24h cap would open or close at the wrong moment. An explicit `Z` or
+ * `±HH:MM` is left alone.
+ */
+export declare function parseUtcTs(ts: string | null | undefined): number | null;
+/** Epoch ms → `'YYYY-MM-DD HH:MM:SS'` (the SQLite `CURRENT_TIMESTAMP` shape, UTC). */
+export declare function formatUtcTs(ms: number): string;
+/** eff(f) — the trust a caller should act on right now (spec §2.2). */
+export declare function effectiveTrust(row: TrustRow, clock: number, cfg: TrustConfig, enabled?: boolean): number;
+/**
+ * What a caller should SEE for a row — the R11 display rule (spec §6):
+ * `active` → `eff()`; **non-active → the stored value verbatim** (the decay
+ * formula keeps running mathematically for archived rows, so the projection must
+ * not use it), and `enabled=false` → stored value (D12).
+ */
+export declare function displayTrust(row: TrustRow, clock: number, cfg: TrustConfig, enabled?: boolean): number;
+/**
+ * Remaining active days: `eff / step`. `null` for pinned rows, non-active rows and
+ * when trust is disabled — the contract's `remaining_days` (spec §6 / R11).
+ */
+export declare function remainingDays(row: TrustRow, clock: number, cfg: TrustConfig, enabled?: boolean): number | null;
+/** Everything a recall write needs to persist (spec §2.3). */
+export interface RecallOutcome {
+    /** `trust_score` after settling the decay at `clock`. */
+    settled: number;
+    /** Final `trust_score` (equals `settled` when no bonus was granted). */
+    next: number;
+    granted: boolean;
+    bonusCount: number;
+    windowAt: string;
+}
+/**
+ * Apply one recall to a fact: settle, then grant a bonus inside the daily quota.
+ * Returns `next === settled` when the quota is exhausted, the ceiling is reached,
+ * the fact is pinned, or the gain would be zero (R2/R10/D11).
+ */
+export declare function grantRecallBonus(row: TrustRow, clock: number, nowMs: number, cfg: TrustConfig, enabled?: boolean): RecallOutcome;
+/** Everything a feedback write needs to persist (spec §2.4). */
+interface FeedbackOutcome {
+    settled: number;
+    next: number;
+    pin: boolean;
+    forget: boolean;
+    /** true when the row was left untouched (pinned / archived). */
+    untouched: boolean;
+    bonusCount: number;
+    windowAt: string;
+}
+/**
+ * Apply one explicit `helpful` (+1) / `unhelpful` (-1) step.
+ *
+ * Pinned and archived rows are untouched (R7): only `helpful_count` changes for
+ * them, so a pinned fact can never end up storing 0.95 while displaying 1.0.
+ * When `feedback_daily_cap > 0` feedback shares the per-fact 24h window counter.
+ */
+export declare function applyFeedbackDelta(row: TrustRow, clock: number, delta: number, nowMs: number, cfg: TrustConfig, enabled?: boolean): FeedbackOutcome;
+export {};