@jmtrin/opencode-kevin 1.1.0 → 1.3.0

package/dist/plugin/Materializer.js

@@ -1,181 +0,0 @@
-import { homedir } from "node:os";
-import { join } from "node:path";
-import { firstSentence } from "./Curator.js";
-import { normalize } from "./fingerprint.js";
-import { STOP_WORDS } from "./query-tokenizer.js";
-export const SKILL_TOPIC = "project-knowledge";
-/** Hash-like noise: FNV-1a output is 16 lowercase hex chars; an 8+ hex
- * token is indistinguishable from a fingerprint prefix and must never
- * become a topic (D6-14). */
-const HEX_LIKE_RE = /^[0-9a-f]{8,}$/;
-const TOKEN_RE = /[^a-z0-9]+/;
-/** Sanitize a memory type into a filesystem-safe topic prefix. */
-function sanitizeType(type) {
-    const cleaned = type
-        .toLowerCase()
-        .replace(/[^a-z0-9]+/g, "-")
-        .replace(/-+/g, "-")
-        .replace(/^-|-$/g, "");
-    return cleaned === "" ? "memory" : cleaned;
-}
-function tokensOf(content) {
-    return normalize(content)
-        .split(TOKEN_RE)
-        .filter((t) => t !== "" && !STOP_WORDS.has(t) && !HEX_LIKE_RE.test(t));
-}
-/** Highest-frequency non-stop-word token, ties broken lexicographically
- * (smallest wins) so the result is stable. "" when every token is a
- * stop-word or hash-like noise. */
-function dominantToken(rows) {
-    const counts = new Map();
-    for (const row of rows) {
-        for (const token of tokensOf(row.content)) {
-            counts.set(token, (counts.get(token) ?? 0) + 1);
-        }
-    }
-    let best = "";
-    let bestCount = 0;
-    for (const [token, count] of counts) {
-        if (count > bestCount || (count === bestCount && token < best)) {
-            best = token;
-            bestCount = count;
-        }
-    }
-    return best;
-}
-function renderRows(rows) {
-    const sorted = [...rows].sort((a, b) => a.id.localeCompare(b.id));
-    const lines = sorted
-        .map((row) => `- ${firstSentence(row.content)}`)
-        .filter((line) => line !== "- ");
-    return lines.length === 0 ? "" : `${lines.join("\n")}\n`;
-}
-export class Materializer {
-    store;
-    /** `root` is injectable for tests; production defaults to ~/.opencode-kevin. */
-    root;
-    /**
-     * v0.9.0 (K9-016 / plan §5.4, D9-10) — the mutual-exclusion guard.
-     * A surface `attachNative()` registered is skipped by `materialize()`
-     * for that surface only; the other surface keeps emitting.
-     */
-    nativeRegistered = new Set();
-    constructor(store, options = {}) {
-        this.store = store;
-        this.root = options.root ?? join(homedir(), ".opencode-kevin");
-    }
-    /**
-     * v0.9.0 (K9-016 / plan §5.4, D9-10) — record whether the surface was
-     * registered natively. Called at attach time (index.ts wiring, K9-018)
-     * with each `NativeRegistration.registered` flag.
-     */
-    markNativeRegistered(surface, registered) {
-        if (registered)
-            this.nativeRegistered.add(surface);
-        else
-            this.nativeRegistered.delete(surface);
-    }
-    /** v0.9.0 (K9-016 / plan §5.4, D9-10) — is the surface registered natively? */
-    hasNativeRegistration(surface) {
-        return this.nativeRegistered.has(surface);
-    }
-    /** The curated, active memories — the knowledge the pull channels publish. */
-    curatedRows() {
-        return this.store
-            .prepare(`SELECT id, type, content FROM memories
-				 WHERE status = 'active' AND curated = 1`)
-            .all();
-    }
-    /** The rendered skill body over all curated memories; "" when empty. */
-    skillBody() {
-        return renderRows(this.curatedRows());
-    }
-    /** Group rows by type, deriving each type's topic from its own content. */
-    groupByTopic(rows) {
-        const byType = new Map();
-        for (const row of rows) {
-            const list = byType.get(row.type) ?? [];
-            list.push(row);
-            byType.set(row.type, list);
-        }
-        const groups = [];
-        for (const [type, typeRows] of byType) {
-            const token = dominantToken(typeRows);
-            if (token === "")
-                continue;
-            groups.push({
-                topic: `${sanitizeType(type)}-${token}`,
-                rows: typeRows,
-            });
-        }
-        return groups.sort((a, b) => a.topic.localeCompare(b.topic));
-    }
-    /**
-     * The pull-channel targets: the skill file plus one ref file per topic.
-     * The order is deterministic (skill first, refs by topic).
-     */
-    bundleTargets() {
-        const rows = this.curatedRows();
-        const targets = [];
-        if (rows.length > 0 && renderRows(rows) !== "") {
-            targets.push({
-                topic: SKILL_TOPIC,
-                path: join(this.root, "skills", "project-knowledge.md"),
-            });
-        }
-        for (const group of this.groupByTopic(rows)) {
-            if (renderRows(group.rows) === "")
-                continue;
-            targets.push({
-                topic: group.topic,
-                path: join(this.root, "refs", `${group.topic}.md`),
-            });
-        }
-        return targets;
-    }
-    /**
-     * Regenerate every bundle through the ArtifactWriter (write). This is
-     * a call site of `write()` — the single write FUNCTION with two
-     * constrained targets: `kevin_approve` reaches `agents_md_path`, this
-     * module reaches `~/.opencode-kevin` only (D6-07; enforced by K6-020).
-     *
-     * v0.9.0 (K9-016 / plan §5.4, D9-10) — the guard: a surface registered
-     * natively by `attachNative()` is skipped here for that surface only.
-     * Both active would put the curated skill in front of the model twice
-     * from two sources that can disagree; neither active would silently
-     * remove the feature on hosts that gained the subpath.
-     */
-    materialize(writer) {
-        const pending = [];
-        const rows = this.curatedRows();
-        const skillBody = renderRows(rows);
-        if (skillBody !== "" && !this.nativeRegistered.has("skill")) {
-            pending.push({
-                topic: SKILL_TOPIC,
-                path: join(this.root, "skills", "project-knowledge.md"),
-                body: skillBody,
-            });
-        }
-        if (!this.nativeRegistered.has("reference")) {
-            for (const group of this.groupByTopic(rows)) {
-                const body = renderRows(group.rows);
-                if (body === "")
-                    continue;
-                pending.push({
-                    topic: group.topic,
-                    path: join(this.root, "refs", `${group.topic}.md`),
-                    body,
-                });
-            }
-        }
-        return pending.map((bundle) => ({
-            topic: bundle.topic,
-            path: bundle.path,
-            outcome: writer.write({
-                path: bundle.path,
-                mode: "markers",
-                content: bundle.body,
-            }),
-        }));
-    }
-}

package/dist/plugin/MemoryService.d.ts

@@ -1,360 +0,0 @@
-import type { Store } from "./Store.js";
-import type { Metrics } from "./metrics.js";
-export type MemoryType = "error" | "pattern" | "decision" | "context" | "rule" | "solution";
-export type MemoryScope = "project" | "session";
-export type MemoryOrigin = "reflector" | "agent" | "pattern" | "retrospective" | "causal" | "imported";
-export interface Memory {
-    id: string;
-    type: MemoryType;
-    content: string;
-    scope: MemoryScope;
-    relevanceScore: number;
-    sourceTool?: string | null;
-    sourceSession?: string | null;
-    metadata?: Record<string, unknown> | null;
-    createdAt: string;
-    updatedAt: string;
-    expiresAt?: string | null;
-    /** v0.2.0 — project the memory belongs to (nullable for legacy rows). */
-    projectId?: string | null;
-    /** v0.2.0 — content fingerprint for dedup (only set for `type='error'`). */
-    fingerprint?: string | null;
-    /** v0.2.0 — origin of the memory. */
-    origin?: MemoryOrigin | null;
-    /** v0.3.0 — confidence derived from causal evidence (0..1). Only set by CausalChain. */
-    confidence?: number | null;
-    /** v0.3.0 — number of confirmed causal fix confirmations. */
-    evidenceCount?: number | null;
-    /** v0.3.0 — last time causal evidence was observed. */
-    lastVerifiedAt?: string | null;
-    /** v0.3.0 — lifecycle status. Default 'active'. */
-    status?: string | null;
-    /** v0.4.0 — deterministic capture of the linked fix call (K4-014). */
-    fixArgs?: string | null;
-    /** v0.4.0 (BUG-008/010) — negative evidence: how many times the
-     * fingerprint recurred after injection (demotes confidence). */
-    recurrenceCount?: number | null;
-    /** v0.5.0 (K5-009 / plan §5.3, D5-07) — human verdict: ignored memories
-     * are excluded from retrieval and injection. */
-    ignored?: boolean;
-    /** v0.5.0 (K5-009 / plan §5.3) — id of the memory that superseded this
-     * one (decision/rule replacement, K3-014). Null when active. */
-    supersedes?: string | null;
-    /** v0.5.0 (K5-010 / plan §5.3, D5-02) — human judgement counters,
-     * folded into confidence by computeConfidence. */
-    feedbackPositive?: number;
-    /** v0.6.0 (K6-011 / plan §5.4) — curation state: curated memories have
-     * been written to AGENTS.md and are excluded from new candidates. */
-    curated?: boolean;
-    /** v0.6.0 (K6-011 / plan §5.4) — when the memory was curated (ISO time). */
-    curatedAt?: string | null;
-    /** v0.6.0 (K6-011 / plan §5.3) — deterministic inferability verdict from
-     * `inferability.classify()`; `null` = unknown, never collapsed. */
-    inferable?: "inferable" | "non_inferable" | null;
-    /** v0.5.0 (K5-010 / plan §5.3, D5-02) — human judgement counters,
-     * folded into confidence by computeConfidence. */
-    feedbackNegative?: number;
-    /** v0.7.0 (K7-008 / plan §5.3, D7-03) — de-ranking penalty in
-     * [0, 0.5], clamped by applyTruthPenalty. Multiplies rankScore as
-     * `(1 - truthPenalty)`. Defaults to 0. */
-    truthPenalty?: number | null;
-    /** v0.7.0 (K7-008 / plan §5.3, D7-03) — first contradiction timestamp. */
-    contradictedAt?: string | null;
-    /** v0.8.0 (K8-018 / plan §5.2) — the memory's layer marker: 'local'
-     * (default) or 'shared'. */
-    layer?: string | null;
-}
-/**
- * v0.8.0 (K8-018 / plan §5.2) — outcome of `update()`. A refusal is a
- * typed value, never a throw and never a silent no-op.
- */
-export type MemoryUpdateResult = {
-    ok: true;
-} | {
-    ok: false;
-    refused: readonly string[];
-};
-export interface SaveInput {
-    type: MemoryType;
-    content: string;
-    /** v0.4.0 (BUG-008) — preserve the original id on okf import;
-     * when absent a fresh uuidv7 is generated. */
-    id?: string;
-    scope?: MemoryScope;
-    relevanceScore?: number;
-    sourceTool?: string;
-    sourceSession?: string;
-    metadata?: Record<string, unknown>;
-    expiresAt?: string;
-    /** v0.2.0 — project id. When absent, the memory is cross-project (NULL project_id). */
-    projectId?: string;
-    /** v0.2.0 — origin. Defaults to `'agent'` when omitted. */
-    origin?: MemoryOrigin;
-    /** v0.2.0 — explicit fingerprint. Auto-derived for `type='error'` if absent. */
-    fingerprint?: string;
-    /** v0.3.0 — number of confirmed causal fix confirmations. */
-    evidenceCount?: number;
-    /** v0.3.0 — last time causal evidence was observed. */
-    lastVerifiedAt?: string;
-    /** v0.3.0 — lifecycle status. Default 'active'. */
-    status?: string;
-    /** v0.4.0 (BUG-008/010) — how many times the fingerprint recurred
-     * after injection (negative evidence, demotes confidence). */
-    recurrenceCount?: number;
-}
-export interface QueryInput {
-    text: string;
-    type?: string;
-    scope?: MemoryScope | "all";
-    limit?: number;
-    /** v0.2.0 — when true, returns full `Memory` rows (v0.1.x behavior).
-     * When `false` or absent, returns `SlimMemory` rows (default v0.2.0
-     * behavior, per plan §B6.3 / K2-010).
-     */
-    full?: boolean;
-    /** v0.3.0 — when true, includes rows where status = 'superseded'.
-     * Default false (only active rows). */
-    includeSuperseded?: boolean;
-    /** v0.3.0 (BUG-001) — when true, the slim payload also carries
-     * `confidence`, `evidence_count` and `last_verified_at` (v0.3.0 K3
-     * evidence fields). Default false (minimal slim shape). */
-    evidence?: boolean;
-}
-/** v0.2.0 — slim query payload (K2-010). Snippet is a short content prefix;
- * `score` is the FTS5 BM25 score when available, falling back to
- * `relevanceScore` for non-FTS callers. */
-export interface SlimMemory {
-    id: string;
-    type: MemoryType;
-    scope: MemoryScope;
-    score: number;
-    snippet: string;
-}
-/** v0.3.0 (BUG-001) — slim payload extended with the evidence fields when
- * `query({ evidence: true })`. Fills the `kevin_query(evidence: true)`
- * contract without falling back to the full `Memory` shape. */
-export interface SlimMemoryWithEvidence extends SlimMemory {
-    confidence: number | null;
-    evidence_count: number | null;
-    last_verified_at: string | null;
-}
-export interface GetRelevantInput {
-    query?: string;
-    maxTokens?: number;
-    scope?: MemoryScope | "all";
-    /** v0.3.0 — when true, includes rows where status = 'superseded'.
-     * Default false (only active rows). */
-    includeSuperseded?: boolean;
-    /**
-     * v0.4.0 (BUG-016) — when false, the relevance bump (K2-023) is
-     * skipped. Used by ContextInjector's probe fetch so the decision and
-     * any retry both see the ORIGINAL ranking; the single bump is applied
-     * by the fetch that actually produces the injected block.
-     */
-    bump?: boolean;
-    /**
-     * v0.5.0 (K5-008 / plan §5.6, D5-10) — injectable clock. Defaults to
-     * `new Date()` at the top of the method and is the ONLY time source
-     * for recency decay: replay and tests can freeze time. Never call
-     * `Date.now()` again inside the method.
-     */
-    now?: Date;
-}
-interface MemoryRow {
-    id: string;
-    type: MemoryType;
-    content: string;
-    scope: MemoryScope;
-    relevance_score: number;
-    source_tool: string | null;
-    source_session: string | null;
-    metadata: string | null;
-    created_at: string;
-    updated_at: string;
-    expires_at: string | null;
-    /** v0.2.0 columns — nullable for rows from pre-003 DBs. */
-    project_id?: string | null;
-    fingerprint?: string | null;
-    origin?: MemoryOrigin | null;
-    /** v0.3.0 */
-    evidence_count?: number;
-    last_verified_at?: string | null;
-    status?: string;
-    /** v0.4.0 */
-    recurrence_count?: number;
-    /** v0.4.0 */
-    fix_args?: string | null;
-    /** v0.5.0 (K5-009) */
-    ignored?: number;
-    /** v0.5.0 (K5-009) */
-    superseded_by?: string | null;
-    /** v0.5.0 (K5-010) */
-    feedback_positive?: number;
-    /** v0.5.0 (K5-010) */
-    feedback_negative?: number;
-    /** v0.6.0 (K6-011 / migration 007) */
-    curated?: number;
-    /** v0.6.0 (K6-011 / migration 007) */
-    curated_at?: string | null;
-    /** v0.6.0 (K6-011 / migration 007) — 1 = inferable, 0 = non_inferable,
-     * NULL = unknown. */
-    inferable?: number | null;
-    /** v0.7.0 (K7-008 / migration 008) — de-ranking penalty in [0, 0.5]. */
-    truth_penalty?: number | null;
-    /** v0.7.0 (K7-008 / migration 008) — first contradiction timestamp. */
-    contradicted_at?: string | null;
-    /** v0.8.0 (K8-018 / migration 009) — layer marker on the row. */
-    layer?: string | null;
-}
-export declare const DATE_NOW = "2099-01-01T00:00:00.000Z";
-export declare function hasRepoIdColumn(store: Store): boolean;
-export declare function mapRow(row: MemoryRow, score?: number): Memory;
-export declare class MemoryService {
-    private readonly metrics;
-    constructor(store: Store, metrics?: Metrics | null, repoId?: string | null);
-    private store;
-    private repoId;
-    setRepoId(repoId: string | null): void;
-    private hasRecurrenceColumn;
-    private hasIgnoredColumn;
-    private hasCuratedColumn;
-    private hasTruthColumns;
-    private hasRepoIdColumn;
-    save(input: SaveInput): string;
-    /**
-     * v0.6.0 (K6-011 / plan §5.4) — mark memories as curated. Batch in a
-     * single statement with an `IN` clause; do not loop. Returns the number
-     * of rows matched by the statement (not only rows whose value changed):
-     * a second call with the same ids re-matches them, so the caller must
-     * re-filter the id list (e.g. by `curated = 0`) to observe 0.
-     */
-    markCurated(ids: readonly string[], at: string): number;
-    getById(id: string): Memory | null;
-    /**
-     * v0.4.0 (K4-016) — most recent ACTIVE memory for a fingerprint,
-     * optionally filtered by type. Feeds the HITL suggestion lookup
-     * (most-recurred fingerprint → its pattern memory).
-     */
-    getByFingerprint(fingerprint: string, type?: MemoryType): Memory | null;
-    /**
-     * v0.8.0 (K8-018 / plan §5.2) — result of a memory mutation.
-     * `refused` lists the shared-layer columns that were not written.
-     */
-    update(id: string, fields: Partial<Memory>): MemoryUpdateResult;
-    /**
-     * v0.8.0 (K8-018 / plan §5.2) — count a refused shared-row write. The
-     * key lives OUTSIDE the frozen METRIC_KEYS ladder (K7-004), following
-     * the v0.6.0 `incrRegistered` precedent: it persists to the same
-     * `kevin_metrics` table and is read back by `kevin_audit` as a bare SQL
-     * scalar, so the counter survives across processes without growing the
-     * 39-key ladder.
-     */
-    private countSharedRefusal;
-    /**
-     * v0.7.0 (K7-008 / plan §5.3, D7-03) — apply a bounded truth penalty.
-     * Clamps `penalty` to [0, 0.5], writes `truth_penalty` and `contradicted_at`,
-     * and increments `memories_contradicted` ONLY when the value moves from 0
-     * to non-zero (a second penalty on the same memory does not re-count).
-     * It NEVER writes `status` — contradiction de-ranks; it never deletes
-     * (Principle 24). `reason` is the human-readable explanation surfaced by
-     * `kevin_facts`; the caller persists it in the `memory_conflicts` row.
-     */
-    applyTruthPenalty(memoryId: string, penalty: number, reason: string): void;
-    delete(id: string): void;
-    /** v0.1.x behavior — returns full `Memory` rows. */
-    query(input: QueryInput & {
-        full: true;
-    }): Memory[];
-    /** v0.3.0 (BUG-001) — slim rows carrying the evidence fields. */
-    query(input: QueryInput & {
-        evidence: true;
-    }): SlimMemoryWithEvidence[];
-    /** v0.2.0 default — returns `SlimMemory` rows. */
-    query(input: QueryInput): SlimMemory[];
-    private isCrossProjectEnabled;
-    /**
-     * v0.4.0 (K4-012) — read a kevin_settings flag by key. Falls back to
-     * the caller-provided default when the key is missing or the table is
-     * unavailable (legacy DB without the settings table).
-     */
-    getSetting(key: string, fallback?: string): string;
-    private loadAll;
-    private queryRelevant;
-    getRelevant(input: GetRelevantInput): Memory[];
-    /**
-     * v0.4.0 (BUG-016) — apply the K2-023 relevance bump to a fixed slice
-     * of ids, exactly once. Lets ContextInjector probe without mutating
-     * and still bump the slice it actually injects.
-     */
-    bumpRelevance(ids: string[]): void;
-    /**
-     * v0.3.0 (K3-004) — Promote an error memory to a causal pattern.
-     *
-     * Creates a new `pattern` memory with `origin = 'causal'`, derived
-     * confidence, and evidence count. The original error memory is NOT
-     * deleted — the audit trail is preserved. Returns the new memory id,
-     * or null when the source error is not eligible (missing fingerprint,
-     * wrong type, or already promoted).
-     */
-    /**
-     * v0.4.0 (K4-009) — returns `{ id, created }` so callers can tell a
-     * newly-created pattern from an idempotent refresh.
-     */
-    promoteToPattern(errorId: string, evidenceCount: number, recurrenceCount?: number): {
-        id: string;
-        created: boolean;
-    } | null;
-    /**
-     * v0.2.0 (K2-026) — Feedback loop positive half (plan §B6.10 / D2-10).
-     *
-     * For each reflector-sourced error memory emitted during the given session
-     * whose fingerprint did NOT recur as a failing `tool_call` within the same
-     * project, bump `relevance_score` by `RELEVANCE_BUMP` (capped at
-     * `RELEVANCE_MAX`). Agent-saved memories are NEVER auto-boosted by this
-     * loop (anti-gaming guarantee, D2-06).
-     *
-     * Returns the number of memories that received a positive boost.
-     */
-    boostPositiveReflectors(sessionId: string): number;
-    /**
-     * v0.3.0 (K3-013) — Feedback loop negative half.
-     *
-     * For each reflector-sourced error memory from this session whose
-     * fingerprint DID recur as a failing tool_call (the lesson didn't
-     * prevent the error), decrement `relevance_score` by `RELEVANCE_PENALTY`
-     * (down to zero) and increment `evidence_count` as a negative signal.
-     * Agent-saved memories are NEVER penalized.
-     *
-     * Returns the number of memories penalized.
-     */
-    /**
-     * v0.3.0 fix — Mirror of the free function `countSupersedeCandidates`
-     * exposed as an instance method so `okf-import` (which holds a
-     * `MemoryService` reference but not the underlying `Store`) can count
-     * rows that `save()` will mark as superseded.
-     */
-    countSupersedeCandidates(type: MemoryType, fingerprint: string | null | undefined, projectId: string | null): number;
-    penalizeRecurringReflectors(sessionId: string): number;
-}
-/**
- * v0.3.0 fix — Extract `origin_call_id` from the memory metadata blob.
- *
- * Reflector stores the failing tool_call id in metadata.origin_call_id
- * (when available) so the feedback loop can exclude the original call
- * from the recurrence count. Returns null when metadata is absent,
- * malformed, or lacks the field.
- * // v1.1.0 (K11-003 / plan §5.5, D11-05) — single source for origin lookup;
- * // InjectionLedger reuses this implementation (K11-013).
- */
-export declare function readOriginCallId(metadata: string | null): string | null;
-/**
- * v0.3.0 fix — Count active memories that would be superseded by a new
- * row with the given (type, fingerprint, projectId) tuple. Used by
- * `okf-import` to populate `ImportResult.superseded` accurately.
- *
- * Matches the supersede logic in `save()`: only `decision` and `rule`
- * types supersede prior rows with the same fingerprint. Returns 0 for
- * any other type.
- */
-export declare function countSupersedeCandidates(store: Store, type: MemoryType, fingerprint: string | null | undefined, projectId: string | null): number;
-export {};