@jmtrin/kevin-core 1.3.0

package/dist/inferability.d.ts

@@ -0,0 +1,32 @@
+/**
+ * K6-010 — v0.6.0 pull — deterministic error-knowledge classifier (plan §5.3).
+ *
+ * Pure module: no DB, no clock, no filesystem, no RNG. Fully unit-testable in
+ * isolation, and therefore fully unit-tested.
+ */
+export type Inferability = "inferable" | "non_inferable" | "unknown";
+/**
+ * The `Reflector` dispatch surface of §3.4, restated as data: error codes whose
+ * payload IS the knowledge — no project-specific interpretation required.
+ */
+export declare const SELF_DESCRIBING_CODES: ReadonlySet<string>;
+/**
+ * Rules from plan §5.3, evaluated in order — the ordering is the specification:
+ *
+ *  1. `type` ∈ decision / rule / solution → `non_inferable`
+ *  2. `type` = pattern → `non_inferable`
+ *  3. `type` = error and `metadata.dispatch.code` ∈ SELF_DESCRIBING_CODES → `inferable`
+ *  4. `type` = error and content names a project-specific path, script or flag → `non_inferable`
+ *  5. otherwise → `unknown`
+ *
+ * Rule 4 beats rule 3: a TS2304 is inferable, but "TS2304 on
+ * `./scripts/gen-routes.ts` because the generator must run before tsc" is not —
+ * the project-specific script name is the payload, not the code. Rule 3's
+ * condition (code membership) is evaluated first for the bare case; rule 4
+ * catches what rule 3 does not.
+ */
+export declare function classify(memory: {
+    type: string;
+    content: string;
+    metadata?: unknown;
+}): Inferability;

package/dist/inferability.js

@@ -0,0 +1,88 @@
+/**
+ * K6-010 — v0.6.0 pull — deterministic error-knowledge classifier (plan §5.3).
+ *
+ * Pure module: no DB, no clock, no filesystem, no RNG. Fully unit-testable in
+ * isolation, and therefore fully unit-tested.
+ */
+/**
+ * The `Reflector` dispatch surface of §3.4, restated as data: error codes whose
+ * payload IS the knowledge — no project-specific interpretation required.
+ */
+export const SELF_DESCRIBING_CODES = new Set([
+    "TS2304",
+    "TS2307",
+    "TS2322",
+    "TS2339",
+    "TS2305",
+    "TS2552",
+    "TS2740",
+    "TS6133",
+    "TS18047",
+    "E0433",
+    "E0432",
+    "command_not_found",
+]);
+/**
+ * Rule 4 detector — deliberately conservative. Errs toward `non_inferable`,
+ * because a false `inferable` silently withholds real knowledge from curation
+ * forever, while a false `non_inferable` costs one line a human rejects.
+ */
+const NPM_RUN_RE = /\b(?:npm|pnpm|yarn|bun)(?:\s+(?:run|exec))?\s+[\w@:/-]+/;
+const RELATIVE_PATH_RE = /\.{1,2}\/[\w./@-]+/;
+const FLAG_RE = /(?:^|\s)--[\w-]+/;
+const FILE_EXT_RE = /\b[\w./@-]+\.[a-zA-Z][a-zA-Z0-9]{0,7}\b/;
+function namesProjectSpecific(content) {
+    return (NPM_RUN_RE.test(content) ||
+        RELATIVE_PATH_RE.test(content) ||
+        FLAG_RE.test(content) ||
+        FILE_EXT_RE.test(content));
+}
+function dispatchCode(metadata) {
+    if (metadata === null || typeof metadata !== "object")
+        return null;
+    const dispatch = metadata.dispatch;
+    if (dispatch === null || typeof dispatch !== "object")
+        return null;
+    const code = dispatch.code;
+    return typeof code === "string" && code.length > 0 ? code : null;
+}
+/**
+ * Rules from plan §5.3, evaluated in order — the ordering is the specification:
+ *
+ *  1. `type` ∈ decision / rule / solution → `non_inferable`
+ *  2. `type` = pattern → `non_inferable`
+ *  3. `type` = error and `metadata.dispatch.code` ∈ SELF_DESCRIBING_CODES → `inferable`
+ *  4. `type` = error and content names a project-specific path, script or flag → `non_inferable`
+ *  5. otherwise → `unknown`
+ *
+ * Rule 4 beats rule 3: a TS2304 is inferable, but "TS2304 on
+ * `./scripts/gen-routes.ts` because the generator must run before tsc" is not —
+ * the project-specific script name is the payload, not the code. Rule 3's
+ * condition (code membership) is evaluated first for the bare case; rule 4
+ * catches what rule 3 does not.
+ */
+export function classify(memory) {
+    // Rule 1 — authored knowledge is never re-derived.
+    if (memory.type === "decision" ||
+        memory.type === "rule" ||
+        memory.type === "solution") {
+        return "non_inferable";
+    }
+    // Rule 2 — a mined sequence is project-specific by construction.
+    if (memory.type === "pattern") {
+        return "non_inferable";
+    }
+    if (memory.type === "error") {
+        const code = dispatchCode(memory.metadata);
+        // Rule 4 — content naming a project-specific path, script or flag.
+        if (namesProjectSpecific(memory.content)) {
+            return "non_inferable";
+        }
+        // Rule 3 — a bare self-describing code is inferable.
+        if (code !== null && SELF_DESCRIBING_CODES.has(code)) {
+            return "inferable";
+        }
+    }
+    // Rule 5.
+    return "unknown";
+}

package/dist/kevin_approve.d.ts

@@ -0,0 +1,34 @@
+import type { ArtifactWriter } from "./ArtifactWriter.js";
+import type { Curator, ProposalStatus } from "./Curator.js";
+import type { MemoryService } from "./MemoryService.js";
+import type { Store } from "./Store.js";
+import type { Metrics } from "./metrics.js";
+/**
+ * K6-014 — v0.6.0 pull — `kevin_approve` tool logic.
+ *
+ * The ONLY code path in the entire plugin that may call
+ * `ArtifactWriter`'s apply method (D6-01; enforced by
+ * tests/unit/single_write_path.test.ts).
+ *
+ * There is deliberately no "trusted mode" and no flag that skips the human:
+ * the approval gate is the release's entire safety model.
+ */
+export interface ApproveArgs {
+    readonly proposalId: string;
+    readonly decision: "approve" | "reject";
+}
+export type ApproveResult = {
+    readonly proposalId: string;
+    readonly status: "rejected";
+} | {
+    readonly proposalId: string;
+    readonly status: "applied";
+    readonly outcome: string;
+    readonly curated: number;
+} | {
+    readonly error: "not_found" | "not_pending";
+    readonly proposalId: string;
+    readonly status?: ProposalStatus;
+    readonly message: string;
+};
+export declare function kevinApprove(store: Store, memoryService: MemoryService, curator: Curator, writer: ArtifactWriter, metrics: Metrics | null, args: ApproveArgs): ApproveResult;

package/dist/kevin_approve.js

@@ -0,0 +1,52 @@
+export function kevinApprove(store, memoryService, curator, writer, metrics, args) {
+    const row = store
+        .prepare(`SELECT id, kind, target_path, proposed_text, memory_id, status
+			 FROM curation_proposals WHERE id = ?`)
+        .get(args.proposalId);
+    if (!row) {
+        return {
+            error: "not_found",
+            proposalId: args.proposalId,
+            message: `No proposal with id "${args.proposalId}".`,
+        };
+    }
+    if (row.status !== "pending") {
+        return {
+            error: "not_pending",
+            proposalId: args.proposalId,
+            status: row.status,
+            message: `Proposal "${args.proposalId}" is ${row.status}, not pending.`,
+        };
+    }
+    if (args.decision === "reject") {
+        curator.transition(args.proposalId, "reject");
+        metrics?.incr("proposals_rejected", 1);
+        return { proposalId: args.proposalId, status: "rejected" };
+    }
+    // approve → apply → applied (plan §5.5). The proposed_text is re-planned
+    // at approval time against the file as it is now; write() is atomic and
+    // audits every outcome including noop. The disk write happens BEFORE the
+    // state transitions: if write() throws (e.g. a filesystem error), the
+    // proposal is still 'pending' and the human can retry or reject — a
+    // row stuck in 'approved' with no file written would be a dead end,
+    // since kevin_approve only accepts pending rows.
+    const outcome = writer.write({
+        path: row.target_path,
+        mode: "markers",
+        content: row.proposed_text,
+    }, args.proposalId);
+    curator.transition(args.proposalId, "approve");
+    curator.transition(args.proposalId, "apply");
+    const memoryIds = row.memory_id.split(",").filter((s) => s.length > 0);
+    const curated = memoryService.markCurated(memoryIds, sqliteNow());
+    metrics?.incr("proposals_approved", 1);
+    return {
+        proposalId: args.proposalId,
+        status: "applied",
+        outcome,
+        curated,
+    };
+}
+function sqliteNow() {
+    return new Date().toISOString().slice(0, 19).replace("T", " ");
+}

package/dist/kevin_audit.d.ts

@@ -0,0 +1,230 @@
+import { type KevinEnv } from "./env.js";
+import type { Store } from "./Store.js";
+import type { Capabilities } from "./capabilities.js";
+import type { Metrics } from "./metrics.js";
+/**
+ * v0.5.0 (K5-016 / plan §5.7) — `kevin_audit`.
+ *
+ * Pure SQL over `memories`, `kevin_injections`, `kevin_metrics`,
+ * `memory_feedback`. No writes, no LLM, no filesystem access.
+ *
+ * There is deliberately **no `kevin_context_ratio`** (D5-09): Kevin cannot
+ * observe total session input tokens, so any such figure would be fabricated.
+ *
+ * Pre-006 databases degrade gracefully: any block that fails (missing column
+ * or table) falls back to its zero value and the report is flagged
+ * `"partial": true` instead of throwing.
+ *
+ * v0.6.0 (K6-023 / plan §5.8) — the `channels` and `curation` blocks are the
+ * release's own scoreboard. On a pre-007 database they are **omitted** (not
+ * zero-valued) and `"partial": true` is set: a report that cannot answer
+ * "do the pull channels beat push?" must say so rather than suggest it can.
+ *
+ * v0.7.0 (K7-019 / plan §5.3, K7-006) — the `truth` block is project-scoped:
+ * facts scanned, penalized memory count and the truncation flag for the
+ * current project. It is omitted (and `"partial": true` set) on a pre-008
+ * database, exactly like the conflicts block. `facts_scanned` counts every
+ * `repo_facts` row for the project — the same COUNT(*) semantics as the
+ * `repo_facts_scanned` metric — while `truncated` reports the scan cap
+ * separately, mirroring `kevin_facts`.
+ */
+export interface AuditReport {
+    memories: {
+        total: number;
+        by_status: Record<string, number>;
+        by_origin: Record<string, number>;
+        by_type: Record<string, number>;
+        ignored: number;
+        archived: number;
+        with_feedback: number;
+        superseded_with_target: number;
+    };
+    injections: {
+        total: number;
+        effective: number;
+        ineffective: number;
+        inconclusive: number;
+        unmeasured: number;
+        precision_rate: number;
+        coverage_rate: number;
+    };
+    blocked: Record<string, number>;
+    feedback: {
+        positive: number;
+        negative: number;
+        by_verdict: Record<string, number>;
+    };
+    tokens: {
+        pre_prompt: number;
+        compacting: number;
+    };
+    settings: Record<string, string>;
+    conflicts?: {
+        by_kind: Record<string, number>;
+        by_status: Record<string, number>;
+    };
+    truth?: TruthReport;
+    mix?: {
+        injected_by_type: Record<string, number>;
+        injected_total: number;
+        non_error_injected: number;
+        non_error_share: number;
+        precision_error: number;
+        precision_non_error: number;
+        meets_exit_criterion: boolean;
+        reason?: "immature_db";
+    };
+    channels?: ChannelReport;
+    curation?: CurationReport;
+    /**
+     * v0.8.0 (K8-018/023 / plan §5.2, §5.7) — the shared-layer block.
+     * K8-018 kept it minimal (write_refusals); K8-023 extends it with
+     * the full team rollup, computed in pure SQL. On a database below
+     * the v0.7.0 maturity floor the precision numbers are omitted and
+     * `reason: "immature_db"` reported instead.
+     */
+    team?: {
+        write_refusals: number;
+        shared_total?: number;
+        tombstones?: number;
+        distinct_authors?: number;
+        last_import_at?: string | null;
+        last_import_rejected?: number;
+        precision_shared?: number;
+        precision_local?: number;
+        reason?: "immature_db";
+    };
+    /**
+     * v0.9.0 (K9-020 / plan §5.5) — the host block, alongside the v0.7.0
+     * `mix` and v0.8.0 `team` blocks. Pure SQL: hook states in aggregate
+     * (live/dead/unknown counts, fires and errors totals), the resolved
+     * plugin version, native registration outcomes per surface, and the
+     * verdict derivable from the database alone. On a pre-010 database
+     * the block is omitted (not zero-valued) and `"partial": true` set,
+     * following the channels/curation precedent.
+     */
+    host?: {
+        plugin_version: string | null;
+        hooks: {
+            live: number;
+            dead: number;
+            unknown: number;
+            fires_total: number;
+            errors_total: number;
+        };
+        native: {
+            total: number;
+            verified: number;
+            failures: number;
+            by_surface: Record<string, {
+                registered: number;
+                verified: number;
+            }>;
+        };
+        verdict: "healthy" | "degraded" | "unknown";
+    };
+    /**
+     * v1.0.0 (K10-020 / plan §5.6) — the perf block: per scope, the most
+     * recent `perf_samples` aggregate row (count/p50/p95/max) plus the
+     * stored budget and verdict. The stored aggregates are used DIRECTLY —
+     * re-aggregating aggregates would produce a number with no meaning
+     * (plan anti-pattern 42), and using the most recent row per scope is
+     * exactly what `bench:check` does, so `within_budget` agrees with it
+     * on the same data. Omitted (not zero-valued) on a pre-011 database,
+     * following the host precedent.
+     */
+    perf?: {
+        scopes: Record<string, {
+            count: number;
+            p50: number;
+            p95: number;
+            max: number;
+            budget_p95: number;
+            within_budget: boolean;
+        }>;
+    };
+    /**
+     * v1.0.0 (K10-020 / plan §5.6) — the contract block: the live contract's
+     * identity, computed from source rather than the database, so it is
+     * present even on a pre-011 database.
+     */
+    contract?: {
+        contract_version: number;
+        digest: string;
+        clause_count: number;
+        deprecated_count: number;
+    };
+    /**
+     * v1.2.0 (K12-014 / D12-??) — TUI surface block. Read-only introspection:
+     * enabled_setting is the kevin_settings value, last_flush_age_s is seconds
+     * since meta.json generatedAt (null when absent/corrupt), mailbox_depth is
+     * queue length (null when file missing), last_results is the parsed
+     * results.json array (null when absent). Dashboard age and bridge counters
+     * added in K12-019.
+     */
+    tui?: {
+        enabled_setting: string;
+        last_flush_age_s: number | null;
+        mailbox_depth: number | null;
+        last_results: unknown | null;
+        dashboard_last_write_age_s: number | null;
+        bridge_interceptions: number;
+    };
+    partial: boolean;
+}
+/**
+ * v0.6.0 (K6-023 / plan §5.8) — three-channel comparison on the same axes.
+ * `skill_emission` / `reference_emission` distinguish the three states a
+ * channel can be in: "unavailable" (v1 host, no domain on the plugin input),
+ * "off" (capable host, setting '0'), "on" (capable host, setting '1').
+ * Collapsing "unavailable" and "off" would make "my host is too old"
+ * indistinguishable from "I turned it off".
+ */
+export type EmissionState = "on" | "off" | "unavailable";
+export interface ChannelReport {
+    push: {
+        tokens_pre_prompt: number;
+        tokens_compacting: number;
+        injections_total: number;
+        precision_rate: number;
+        coverage_rate: number;
+        budget_tokens: number;
+    };
+    pull: {
+        proposals_created: number;
+        proposals_approved: number;
+        proposals_rejected: number;
+        artifact_writes_total: number;
+        artifact_writes_noop: number;
+        references_registered: number;
+        skills_registered: number;
+        skill_emission: EmissionState;
+        reference_emission: EmissionState;
+    };
+}
+export interface CurationReport {
+    eligible: number;
+    curated: number;
+    inferable: number;
+    non_inferable: number;
+    unknown: number;
+    proposals_by_status: Record<string, number>;
+}
+/**
+ * v0.7.0 (K7-019 / plan §5.3) — the Project Truth block. The same shape
+ * `kevin_facts` exposes: `facts_scanned` counts every repo_facts row for the
+ * project (COUNT(*) semantics, matching the `repo_facts_scanned` metric),
+ * `penalized_memories` counts memories with `truth_penalty > 0`, and
+ * `truncated` reports the 500-fact scan cap from the `_truncated` marker row.
+ */
+export interface TruthReport {
+    facts_scanned: number;
+    penalized_memories: number;
+    truncated: {
+        is_truncated: true;
+        count: number;
+    } | {
+        is_truncated: false;
+    };
+}
+export declare function buildAudit(store: Store, metrics: Metrics, capabilities?: Capabilities, projectId?: string, repoId?: string | null, tuiRoot?: string, env?: KevinEnv): AuditReport;