onadit 0.0.1 → 1.0.0

package/dist/src/observability/retrieval-feedback.js

@@ -0,0 +1,231 @@
+/**
+ * Retrieval feedback ledger.
+ *
+ * This is append-only JSONL by design. v0 records positive signals only:
+ * evidence opened via `onadit_open_evidence` and evidence cited via
+ * `onadit_log_outcome`. Returned-but-not-opened hits are not credit; they are
+ * only the denominator/rank context that lets us discount position bias.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { FRESH_HALF_LIFE_DAYS } from "../retrieval/reranker.js";
+export const RETRIEVAL_FEEDBACK_FILE = "retrieval-feedback.jsonl";
+export const B_FEED_NEUTRAL = 1.0;
+export const B_FEED_MAX = 1.25;
+const BOOST_SATURATION_CREDIT = 4;
+export function retrievalFeedbackPath(dataDir) {
+    return path.join(dataDir, "observability", RETRIEVAL_FEEDBACK_FILE);
+}
+export function appendRetrievalFeedbackEvent(dataDir, input) {
+    const timestamp = (input.now ?? new Date()).toISOString();
+    const event = {
+        timestamp,
+        type: input.type,
+        stable_evidence_key: input.identity.stable_evidence_key,
+        evidence_kind: input.identity.evidence_kind,
+        source_table: input.identity.source_table,
+        source_id: input.identity.source_id,
+        ...(input.identity.source_path ? { source_path: input.identity.source_path } : {}),
+        ...(input.identity.parent_id ? { parent_id: input.identity.parent_id } : {}),
+        ...(input.identity.digest_id ? { digest_id: input.identity.digest_id } : {}),
+        ...(input.session_id ? { session_id: input.session_id } : {}),
+        ...(input.tool_call_id ? { tool_call_id: input.tool_call_id } : {}),
+        ...(input.outcome_id ? { outcome_id: input.outcome_id } : {}),
+        ...(input.project ? { project: input.project } : {}),
+        ...(input.intent ? { intent: input.intent } : {}),
+        ...(input.query ? { query: input.query } : {}),
+        ...(input.task ? { task: input.task } : {}),
+        ...(input.rank_at_retrieval !== undefined
+            ? { rank_at_retrieval: input.rank_at_retrieval }
+            : {}),
+        ...(input.result_count !== undefined ? { result_count: input.result_count } : {}),
+        ...(input.context_pack_bucket ? { context_pack_bucket: input.context_pack_bucket } : {}),
+        ...(input.position_in_bucket !== undefined
+            ? { position_in_bucket: input.position_in_bucket }
+            : {}),
+        ...(input.reason ? { reason: input.reason } : {}),
+    };
+    const dedupe = input.dedupe_key ?? defaultDedupeKey(event);
+    if (dedupe)
+        event.dedupe_key = dedupe;
+    if (event.type !== "feedback_reset" && dedupe) {
+        // v0 is single-user and append-only: read the small local ledger to dedupe
+        // repeated tool calls. Replace with an indexed/locked projection before
+        // high-volume or multi-writer use.
+        const existing = readRetrievalFeedbackEvents(dataDir).find((e) => e.dedupe_key === dedupe);
+        if (existing)
+            return { event: existing, written: false, duplicate: true };
+    }
+    const file = retrievalFeedbackPath(dataDir);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.appendFileSync(file, JSON.stringify(event) + "\n", "utf-8");
+    return { event, written: true, duplicate: false };
+}
+export function appendFeedbackReset(dataDir, input) {
+    return appendRetrievalFeedbackEvent(dataDir, {
+        type: "feedback_reset",
+        identity: input.identity,
+        ...(input.session_id ? { session_id: input.session_id } : {}),
+        ...(input.project ? { project: input.project } : {}),
+        ...(input.intent ? { intent: input.intent } : {}),
+        ...(input.reason ? { reason: input.reason } : {}),
+        ...(input.now ? { now: input.now } : {}),
+        dedupe_key: `reset:${input.identity.stable_evidence_key}:${input.now?.toISOString() ?? crypto.randomUUID()}`,
+    });
+}
+export function readRetrievalFeedbackEvents(dataDir) {
+    let raw;
+    try {
+        raw = fs.readFileSync(retrievalFeedbackPath(dataDir), "utf-8");
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const line of raw.split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            if (typeof parsed["timestamp"] === "string" &&
+                typeof parsed["type"] === "string" &&
+                typeof parsed["stable_evidence_key"] === "string") {
+                out.push(parsed);
+            }
+        }
+        catch {
+            // Tolerate corrupt lines; one bad append must not erase the ledger.
+        }
+    }
+    return out;
+}
+export function computeFeedbackBoosts(events, stableEvidenceKeys, scope = {}) {
+    const nowMs = (scope.now ?? new Date()).getTime();
+    const out = new Map();
+    for (const key of stableEvidenceKeys) {
+        const scopedEvents = events.filter((e) => e.stable_evidence_key === key);
+        // Only events that have actually occurred (parseable, not future-dated)
+        // count. A future-dated reset must not suppress real past feedback, and a
+        // future-dated positive must not earn (undecayed) credit before its time.
+        const resets = scopedEvents.filter((e) => e.type === "feedback_reset" &&
+            scopeMatches(e, scope) &&
+            hasOccurred(eventTimeMs(e), nowMs));
+        const positives = scopedEvents.filter((e) => isPositiveEvent(e) &&
+            scopeMatches(e, scope) &&
+            hasOccurred(eventTimeMs(e), nowMs) &&
+            !isResetBy(e, resets));
+        const credit = positives.reduce((sum, e) => sum + eventCredit(e, nowMs), 0);
+        const positiveCount = positives.length;
+        const B_feed = credit <= 0
+            ? B_FEED_NEUTRAL
+            : B_FEED_NEUTRAL +
+                (B_FEED_MAX - B_FEED_NEUTRAL) *
+                    (1 - Math.exp(-credit / BOOST_SATURATION_CREDIT));
+        out.set(key, {
+            stable_evidence_key: key,
+            B_feed,
+            weighted_credit: credit,
+            positive_event_count: positiveCount,
+            reset_count: resets.length,
+            applied: false,
+        });
+    }
+    return out;
+}
+export function explainFeedback(dataDir, stableEvidenceKey, scope = {}) {
+    const events = readRetrievalFeedbackEvents(dataDir);
+    const boost = computeFeedbackBoosts(events, [stableEvidenceKey], scope).get(stableEvidenceKey) ?? {
+        stable_evidence_key: stableEvidenceKey,
+        B_feed: B_FEED_NEUTRAL,
+        weighted_credit: 0,
+        positive_event_count: 0,
+        reset_count: 0,
+        applied: false,
+    };
+    return {
+        ...boost,
+        events: events
+            .filter((e) => e.stable_evidence_key === stableEvidenceKey)
+            .filter((e) => scopeMatches(e, scope)),
+    };
+}
+function defaultDedupeKey(event) {
+    if (event.type === "feedback_reset")
+        return undefined;
+    const session = event.session_id ?? event.tool_call_id;
+    if (!session)
+        return undefined;
+    // Dedupe is scope-aware: the same evidence opened/cited in the same session
+    // but under a different (project, intent) is a distinct positive signal for
+    // that scope, not a duplicate. Keying only on type:session:key would silently
+    // drop the second scope's credit and make scoped why/reset lie.
+    const project = event.project ?? "";
+    const intent = event.intent ?? "";
+    return `${event.type}:${session}:${project}:${intent}:${event.stable_evidence_key}`;
+}
+function isPositiveEvent(e) {
+    return e.type === "evidence_opened" || e.type === "evidence_cited";
+}
+function scopeMatches(e, scope) {
+    if (scope.project !== undefined && e.project !== scope.project)
+        return false;
+    if (!intentMatches(e.intent, scope.intent))
+        return false;
+    return true;
+}
+function intentMatches(eventIntent, scopeIntent) {
+    if (scopeIntent === undefined)
+        return true;
+    if (scopeIntent === "blended")
+        return eventIntent !== undefined;
+    return eventIntent === scopeIntent || eventIntent === "blended";
+}
+function isResetBy(event, resets) {
+    const eventMs = new Date(event.timestamp).getTime();
+    return resets.some((reset) => {
+        const resetMs = new Date(reset.timestamp).getTime();
+        if (Number.isNaN(resetMs) || Number.isNaN(eventMs))
+            return false;
+        if (resetMs < eventMs)
+            return false;
+        if (reset.project !== undefined && event.project !== reset.project)
+            return false;
+        if (!intentMatches(event.intent, reset.intent))
+            return false;
+        return true;
+    });
+}
+function eventTimeMs(event) {
+    return new Date(event.timestamp).getTime();
+}
+/**
+ * Whether an event has actually occurred relative to the evaluation time.
+ * False for unparseable (NaN) timestamps and for future-dated rows — neither
+ * should earn credit, and a future-dated reset must not retroactively suppress
+ * real past feedback up to its timestamp.
+ */
+function hasOccurred(eventMs, nowMs) {
+    return !Number.isNaN(eventMs) && eventMs <= nowMs;
+}
+function eventCredit(event, nowMs) {
+    const eventMs = new Date(event.timestamp).getTime();
+    // A corrupt/unparseable timestamp earns no credit. Returning 0 (rather than
+    // treating it as days=0 → full undecayed credit) keeps a malformed row from
+    // silently inflating B_feed, and mirrors how isResetBy() skips NaN resets.
+    if (Number.isNaN(eventMs))
+        return 0;
+    const days = Math.max(0, (nowMs - eventMs) / 86_400_000);
+    const decay = Math.exp(-days / FRESH_HALF_LIFE_DAYS);
+    const typeWeight = event.type === "evidence_cited" ? 1.5 : 1.0;
+    return typeWeight * positionBiasWeight(event) * decay;
+}
+export function positionBiasWeight(event) {
+    const position = event.context_pack_bucket && typeof event.position_in_bucket === "number"
+        ? event.position_in_bucket
+        : event.rank_at_retrieval;
+    if (typeof position !== "number" || position < 1)
+        return 1.0;
+    return Math.min(3, Math.sqrt(position));
+}
+//# sourceMappingURL=retrieval-feedback.js.map

package/dist/src/observability/retrieval-feedback.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retrieval-feedback.js","sourceRoot":"","sources":["../../../src/observability/retrieval-feedback.ts"],"names":[],"mappings":"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"}

package/dist/src/observability/rift-context.d.ts

@@ -0,0 +1,53 @@
+import { type ConversationSource } from "../providers/types.js";
+export interface CapabilityCounts {
+    /** Total structured documents across cloud + local tables. */
+    structured_docs: number;
+    /** Hot tier conversation rows. */
+    conversations_hot: number;
+    /** Cold tier conversation rows. */
+    conversations_cold: number;
+    /** Digest summary rows. */
+    digests: number;
+}
+export interface CapabilityMapOptions {
+    maintenanceActive?: boolean;
+}
+/**
+ * Hard character cap enforced in tests. 2400 chars is a conservative
+ * ceiling for the plan's 600-token target at ~4 chars/token for
+ * English markdown. Keep the rendered output well below this.
+ */
+export declare const CAPABILITY_MAP_MAX_CHARS = 2400;
+/** Plan-level token target (see PLAN.MD "Capability Map Contract"). */
+export declare const CAPABILITY_MAP_MAX_TOKENS = 600;
+/**
+ * Rough token estimate. Not a tokenizer — uses chars/4 rounded up,
+ * a documented approximation suitable for a size guard. If a real
+ * tokenizer is later added to the repo, swap this implementation.
+ */
+export declare function approxTokenCount(text: string): number;
+/**
+ * Fetch the counts the capability map needs. Uses `countRows()` only
+ * (no full-table `.toArray()` walks). Callers get a small, cheap
+ * object; failures propagate so the route can decide how to respond.
+ */
+export declare function getCapabilityCounts(): Promise<CapabilityCounts>;
+/**
+ * Conversation rows per source, hot + cold tiers summed. Same cheap
+ * `countRows(filter)` contract as above; failures propagate.
+ */
+export declare function getConversationCountsBySource(): Promise<Record<ConversationSource, number>>;
+/**
+ * Generate the capability-map markdown from cheap counts.
+ * Deterministic for identical input; regenerated on each request
+ * (no TTL cache in Phase 1).
+ */
+export declare function generateCapabilityMap(counts: CapabilityCounts, opts?: CapabilityMapOptions): string;
+/**
+ * Write the capability map to `{dataDir}/rift-context.md`.
+ * Best-effort — returns { written: false } on failure without throwing.
+ */
+export declare function writeRiftContext(dataDir: string, capabilityMap: string): Promise<{
+    written: boolean;
+}>;
+//# sourceMappingURL=rift-context.d.ts.map

package/dist/src/observability/rift-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rift-context.d.ts","sourceRoot":"","sources":["../../../src/observability/rift-context.ts"],"names":[],"mappings":"AA6BA,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,uBAAuB,CAAC;AAG/B,MAAM,WAAW,gBAAgB;IAC/B,8DAA8D;IAC9D,eAAe,EAAE,MAAM,CAAC;IACxB,kCAAkC;IAClC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,mCAAmC;IACnC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,2BAA2B;IAC3B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,oBAAoB;IACnC,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,OAAO,CAAC;AAE7C,uEAAuE;AACvE,eAAO,MAAM,yBAAyB,MAAM,CAAC;AAE7C;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAErD;AAED;;;;GAIG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAgBrE;AAED;;;GAGG;AACH,wBAAsB,6BAA6B,IAAI,OAAO,CAC5D,MAAM,CAAC,kBAAkB,EAAE,MAAM,CAAC,CACnC,CAYA;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,gBAAgB,EACxB,IAAI,CAAC,EAAE,oBAAoB,GAC1B,MAAM,CA8ER;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,MAAM,EACf,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC,CAU/B"}

package/dist/src/observability/rift-context.js

@@ -0,0 +1,141 @@
+/**
+ * Generates the Zero-Prompt Awareness capability map served by
+ * GET /status, MCP onadit_status, and CLI `status`, and writes the
+ * `rift-context.md` flat file as a side effect.
+ *
+ * Phase 1 contract (Slice 2):
+ * - introduces Onadit as a capability, not a preloaded prompt
+ * - names the three available memory classes: conversations, digests,
+ *   structured documents
+ * - names the three existing tools and when to use each
+ * - keeps infra metrics secondary (inline counts only)
+ *
+ * Size budget:
+ *   PLAN.MD's Capability Map Contract targets `<= 600 tokens` for the
+ *   markdown form. No tokenizer ships in-repo, so Phase 1 enforces a
+ *   measurable char-based proxy plus a rough chars/4 token estimate.
+ *   Both bounds are comfortably conservative relative to the plan's
+ *   intent and are validated by the test suite.
+ *
+ * Data dependency:
+ *   Generation needs only cheap per-table `countRows()` calls; it must
+ *   not depend on full source-coverage scans (`.toArray()` walks). This
+ *   keeps `/status` fast and keeps it working when secondary
+ *   observability/source-health collection fails.
+ */
+import { atomicWrite } from "../storage/atomic.js";
+import { getTable } from "../storage/tables.js";
+import { REPORT_CARD_SQL_EXCLUSION } from "../ingestion/report-cards.js";
+import { eqFilter } from "../storage/filter.js";
+import { CONVERSATION_SOURCES, } from "../providers/types.js";
+import path from "node:path";
+/**
+ * Hard character cap enforced in tests. 2400 chars is a conservative
+ * ceiling for the plan's 600-token target at ~4 chars/token for
+ * English markdown. Keep the rendered output well below this.
+ */
+export const CAPABILITY_MAP_MAX_CHARS = 2400;
+/** Plan-level token target (see PLAN.MD "Capability Map Contract"). */
+export const CAPABILITY_MAP_MAX_TOKENS = 600;
+/**
+ * Rough token estimate. Not a tokenizer — uses chars/4 rounded up,
+ * a documented approximation suitable for a size guard. If a real
+ * tokenizer is later added to the repo, swap this implementation.
+ */
+export function approxTokenCount(text) {
+    return Math.ceil(text.length / 4);
+}
+/**
+ * Fetch the counts the capability map needs. Uses `countRows()` only
+ * (no full-table `.toArray()` walks). Callers get a small, cheap
+ * object; failures propagate so the route can decide how to respond.
+ */
+export async function getCapabilityCounts() {
+    // beta.28: exclude index cards (catalog pointers, not documents) from the doc
+    // counts so the capability map stays honest after a backfill, flag or no flag.
+    const [sd, sdLocal, hot, cold, digests] = await Promise.all([
+        getTable("structured_docs").countRows(REPORT_CARD_SQL_EXCLUSION),
+        getTable("structured_docs_local").countRows(REPORT_CARD_SQL_EXCLUSION),
+        getTable("conversations_hot").countRows(),
+        getTable("conversations_cold").countRows(),
+        getTable("digests").countRows(),
+    ]);
+    return {
+        structured_docs: sd + sdLocal,
+        conversations_hot: hot,
+        conversations_cold: cold,
+        digests,
+    };
+}
+/**
+ * Conversation rows per source, hot + cold tiers summed. Same cheap
+ * `countRows(filter)` contract as above; failures propagate.
+ */
+export async function getConversationCountsBySource() {
+    const counts = await Promise.all(CONVERSATION_SOURCES.map(async (source) => {
+        const filter = eqFilter("source", source);
+        const [hot, cold] = await Promise.all([
+            getTable("conversations_hot").countRows(filter),
+            getTable("conversations_cold").countRows(filter),
+        ]);
+        return [source, hot + cold];
+    }));
+    return Object.fromEntries(counts);
+}
+/**
+ * Generate the capability-map markdown from cheap counts.
+ * Deterministic for identical input; regenerated on each request
+ * (no TTL cache in Phase 1).
+ */
+export function generateCapabilityMap(counts, opts) {
+    const conversationsTotal = counts.conversations_hot + counts.conversations_cold;
+    const lines = [];
+    lines.push("# Onadit Capability Map");
+    lines.push("");
+    lines.push("Onadit is a local memory service. Agents call it on demand to look up prior conversations, higher-level summaries of past activity, and indexed project or reference documents — not as a preloaded prompt blob. Use the tools below only when relevant context is likely to live in memory.");
+    lines.push("");
+    if (opts?.maintenanceActive) {
+        lines.push("> **Maintenance in progress** — an exclusive job is running. Some indexers are paused; results may be partial.");
+        lines.push("");
+    }
+    lines.push("## Available Memory");
+    lines.push(`- **conversations** — prior chat/session memory (hot + cold tiers). ${conversationsTotal} indexed.`);
+    lines.push(`- **digests** — higher-level summaries of past activity. ${counts.digests} indexed.`);
+    lines.push(`- **structured documents** — indexed project/client/reference files. ${counts.structured_docs} indexed.`);
+    lines.push("");
+    lines.push("## Which Tool To Use");
+    lines.push("- `onadit_search` — broad search across all memory classes. Start here when you do not know which class holds the answer.");
+    lines.push("- `onadit_conversations_search` — conversation-specific search with structured filters (source, domain, intent, decisions, topics). Use when the question is clearly about prior chats.");
+    lines.push("- `onadit_context_pack` — compact bucketed context for an active task (decisions / constraints / examples / rules). Byte-bounded; never returns raw transcripts. Use to steer an agent, not to fetch a ranked hit list.");
+    lines.push("- `onadit_open_evidence` — open one exact compact hit when it is worth inspecting; records a shadow-only feedback event after a successful open.");
+    lines.push("- `onadit_log_outcome` — after substantive work, log what happened and cite only evidence actually used; this records shadow feedback without counting returned-but-unused hits.");
+    lines.push("- `onadit_why_evidence` / `onadit_forget_evidence_feedback` — inspect or reset learned retrieval feedback for a source.");
+    lines.push("- `onadit_status` — system and capability overview (this map). Not for content retrieval.");
+    lines.push("");
+    lines.push("## Default Behavior");
+    lines.push("- Start compact. Issue one focused query before broadening.");
+    lines.push("- Read each compact hit (title, snippet, summary) first. Expand only the specific hit that justifies it.");
+    lines.push("- Do not pull raw history by default. Raw content is archive, not the default payload.");
+    lines.push("");
+    lines.push("## Escalation");
+    lines.push("- Need the full body of a hit? Follow the hit's `expand` pointer (typically `/search` with `detail=\"full\"`).");
+    lines.push("- Need conversation-specific filters (source, decisions, topics)? Switch to `onadit_conversations_search`.");
+    lines.push("- Only broaden the query if the compact search returned no plausible candidate.");
+    lines.push("");
+    return lines.join("\n");
+}
+/**
+ * Write the capability map to `{dataDir}/rift-context.md`.
+ * Best-effort — returns { written: false } on failure without throwing.
+ */
+export async function writeRiftContext(dataDir, capabilityMap) {
+    try {
+        await atomicWrite(path.join(dataDir, "rift-context.md"), capabilityMap);
+        return { written: true };
+    }
+    catch (err) {
+        process.stderr.write(`Failed to write rift-context.md: ${err instanceof Error ? err.message : String(err)}\n`);
+        return { written: false };
+    }
+}
+//# sourceMappingURL=rift-context.js.map

package/dist/src/observability/rift-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rift-context.js","sourceRoot":"","sources":["../../../src/observability/rift-context.ts"],"names":[],"mappings":"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"}

package/dist/src/observability/staleness.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Pure threshold logic for source health and freshness evaluation.
+ *
+ * All time-based functions accept an explicit `now` parameter so callers
+ * can freeze the clock during maintenance windows.
+ */
+import type { Watcher } from "../ingestion/watcher.js";
+/** Unverified-autonomous sources are unhealthy after this many days without a save. */
+export declare const UNVERIFIED_STALENESS_DAYS = 15;
+/** Manual sources are stale after this many days without an ingest. */
+export declare const MANUAL_STALENESS_DAYS = 30;
+/** Scheduled scan freshness SLO: last_scan_at must be within interval × this factor. */
+export declare const SCAN_SLO_SLACK_FACTOR = 1.5;
+/**
+ * Evaluate health of an unverified-autonomous source.
+ * Returns { healthy: true } if the source has a recent save,
+ * or { healthy: false, warning } if stale or no data.
+ */
+export declare function isUnverifiedHealthy(lastSave: string | null, now: Date): {
+    healthy: boolean;
+    warning?: string;
+};
+/**
+ * Evaluate staleness of a manual source.
+ * Returns true if the source has no data or data older than the threshold.
+ */
+export declare function isManualStale(lastIngest: string | null, now: Date): boolean;
+/**
+ * Evaluate whether the scheduled scan freshness SLO is met.
+ * Met when `last_scan_at` is within `intervalSeconds × SCAN_SLO_SLACK_FACTOR` of `now`.
+ */
+export declare function isScanFreshnessMet(lastScanAt: string | null, intervalSeconds: number, now: Date): boolean;
+/**
+ * Evaluate watcher health.
+ * Healthy when maintenance is active (pause is expected) or when not all watchers are paused.
+ * An empty watchers array with no maintenance → true (nothing to be broken).
+ */
+export declare function isWatcherHealthy(watchers: readonly Watcher[], maintenanceActive: boolean): boolean;
+/**
+ * Format a human-readable staleness warning.
+ */
+export declare function formatStalenessWarning(source: string, lastTimestamp: string | null, thresholdDays: number): string;
+//# sourceMappingURL=staleness.d.ts.map

package/dist/src/observability/staleness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"staleness.d.ts","sourceRoot":"","sources":["../../../src/observability/staleness.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAIvD,uFAAuF;AACvF,eAAO,MAAM,yBAAyB,KAAK,CAAC;AAE5C,uEAAuE;AACvE,eAAO,MAAM,qBAAqB,KAAK,CAAC;AAExC,wFAAwF;AACxF,eAAO,MAAM,qBAAqB,MAAM,CAAC;AAWzC;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,GAAG,IAAI,EACvB,GAAG,EAAE,IAAI,GACR;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAYxC;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,EAAE,GAAG,EAAE,IAAI,GAAG,OAAO,CAG3E;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,MAAM,GAAG,IAAI,EACzB,eAAe,EAAE,MAAM,EACvB,GAAG,EAAE,IAAI,GACR,OAAO,CAKT;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,SAAS,OAAO,EAAE,EAC5B,iBAAiB,EAAE,OAAO,GACzB,OAAO,CAIT;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,MAAM,GAAG,IAAI,EAC5B,aAAa,EAAE,MAAM,GACpB,MAAM,CAMR"}

package/dist/src/observability/staleness.js

@@ -0,0 +1,74 @@
+// --- Thresholds ---
+/** Unverified-autonomous sources are unhealthy after this many days without a save. */
+export const UNVERIFIED_STALENESS_DAYS = 15;
+/** Manual sources are stale after this many days without an ingest. */
+export const MANUAL_STALENESS_DAYS = 30;
+/** Scheduled scan freshness SLO: last_scan_at must be within interval × this factor. */
+export const SCAN_SLO_SLACK_FACTOR = 1.5;
+// --- Helpers ---
+function daysSince(timestamp, now) {
+    const then = new Date(timestamp).getTime();
+    return (now.getTime() - then) / (1000 * 60 * 60 * 24);
+}
+// --- Evaluation functions ---
+/**
+ * Evaluate health of an unverified-autonomous source.
+ * Returns { healthy: true } if the source has a recent save,
+ * or { healthy: false, warning } if stale or no data.
+ */
+export function isUnverifiedHealthy(lastSave, now) {
+    if (lastSave === null) {
+        return { healthy: false, warning: "No saves recorded" };
+    }
+    const days = daysSince(lastSave, now);
+    if (days > UNVERIFIED_STALENESS_DAYS) {
+        return {
+            healthy: false,
+            warning: `No saves in ${Math.floor(days)} days`,
+        };
+    }
+    return { healthy: true };
+}
+/**
+ * Evaluate staleness of a manual source.
+ * Returns true if the source has no data or data older than the threshold.
+ */
+export function isManualStale(lastIngest, now) {
+    if (lastIngest === null)
+        return true;
+    return daysSince(lastIngest, now) > MANUAL_STALENESS_DAYS;
+}
+/**
+ * Evaluate whether the scheduled scan freshness SLO is met.
+ * Met when `last_scan_at` is within `intervalSeconds × SCAN_SLO_SLACK_FACTOR` of `now`.
+ */
+export function isScanFreshnessMet(lastScanAt, intervalSeconds, now) {
+    if (lastScanAt === null)
+        return false;
+    const thresholdMs = intervalSeconds * SCAN_SLO_SLACK_FACTOR * 1000;
+    const elapsed = now.getTime() - new Date(lastScanAt).getTime();
+    return elapsed <= thresholdMs;
+}
+/**
+ * Evaluate watcher health.
+ * Healthy when maintenance is active (pause is expected) or when not all watchers are paused.
+ * An empty watchers array with no maintenance → true (nothing to be broken).
+ */
+export function isWatcherHealthy(watchers, maintenanceActive) {
+    if (maintenanceActive)
+        return true;
+    if (watchers.length === 0)
+        return true;
+    return !watchers.every((w) => w.isPaused);
+}
+/**
+ * Format a human-readable staleness warning.
+ */
+export function formatStalenessWarning(source, lastTimestamp, thresholdDays) {
+    if (lastTimestamp === null) {
+        return `${source}: no activity recorded`;
+    }
+    const days = Math.floor(daysSince(lastTimestamp, new Date()));
+    return `${source}: no activity in ${days} days (threshold: ${thresholdDays}d)`;
+}
+//# sourceMappingURL=staleness.js.map

package/dist/src/observability/staleness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"staleness.js","sourceRoot":"","sources":["../../../src/observability/staleness.ts"],"names":[],"mappings":"AAQA,qBAAqB;AAErB,uFAAuF;AACvF,MAAM,CAAC,MAAM,yBAAyB,GAAG,EAAE,CAAC;AAE5C,uEAAuE;AACvE,MAAM,CAAC,MAAM,qBAAqB,GAAG,EAAE,CAAC;AAExC,wFAAwF;AACxF,MAAM,CAAC,MAAM,qBAAqB,GAAG,GAAG,CAAC;AAEzC,kBAAkB;AAElB,SAAS,SAAS,CAAC,SAAiB,EAAE,GAAS;IAC7C,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,CAAC;IAC3C,OAAO,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,CAAC;AACxD,CAAC;AAED,+BAA+B;AAE/B;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CACjC,QAAuB,EACvB,GAAS;IAET,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;QACtB,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,mBAAmB,EAAE,CAAC;IAC1D,CAAC;IACD,MAAM,IAAI,GAAG,SAAS,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;IACtC,IAAI,IAAI,GAAG,yBAAyB,EAAE,CAAC;QACrC,OAAO;YACL,OAAO,EAAE,KAAK;YACd,OAAO,EAAE,eAAe,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO;SAChD,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AAC3B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,UAAyB,EAAE,GAAS;IAChE,IAAI,UAAU,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACrC,OAAO,SAAS,CAAC,UAAU,EAAE,GAAG,CAAC,GAAG,qBAAqB,CAAC;AAC5D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAChC,UAAyB,EACzB,eAAuB,EACvB,GAAS;IAET,IAAI,UAAU,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IACtC,MAAM,WAAW,GAAG,eAAe,GAAG,qBAAqB,GAAG,IAAI,CAAC;IACnE,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,EAAE,GAAG,IAAI,IAAI,CAAC,UAAU,CAAC,CAAC,OAAO,EAAE,CAAC;IAC/D,OAAO,OAAO,IAAI,WAAW,CAAC;AAChC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAC9B,QAA4B,EAC5B,iBAA0B;IAE1B,IAAI,iBAAiB;QAAE,OAAO,IAAI,CAAC;IACnC,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACvC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;AAC5C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,sBAAsB,CACpC,MAAc,EACd,aAA4B,EAC5B,aAAqB;IAErB,IAAI,aAAa,KAAK,IAAI,EAAE,CAAC;QAC3B,OAAO,GAAG,MAAM,wBAAwB,CAAC;IAC3C,CAAC;IACD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,aAAa,EAAE,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC;IAC9D,OAAO,GAAG,MAAM,oBAAoB,IAAI,qBAAqB,aAAa,IAAI,CAAC;AACjF,CAAC"}