@jmtrin/opencode-kevin 1.2.0 → 1.3.0

package/dist/plugin/InjectionLedger.js

@@ -1,295 +0,0 @@
-import { readOriginCallId } from "./MemoryService.js";
-import { hasColumn } from "./columns.js";
-import { toMs } from "./time-ms.js";
-import { uuidv7 } from "./uuid.js";
-export class InjectionLedger {
-    store;
-    metrics;
-    constructor(store, metrics) {
-        this.store = store;
-        this.metrics = metrics ?? null;
-    }
-    /**
-     * Records one injected memory. Idempotent at the row level (UUID PK);
-     * duplicates are expected only via the caller's per-session seen-set.
-     */
-    record(input) {
-        // v1.1.0 (K11-003 / plan §5.2, D11-01) — dual-write injected_at_ms when column exists
-        if (hasColumn(this.store, "kevin_injections", "injected_at_ms")) {
-            this.store
-                .prepare(`INSERT INTO kevin_injections
-					   (id, memory_id, fingerprint, session_id, hook, tokens, outcome, injected_at_ms)
-					 VALUES (?, ?, ?, ?, ?, ?, 'unmeasured', ?)`)
-                .run(uuidv7(), input.memoryId, input.fingerprint, input.sessionId, input.hook, input.tokens, Date.now());
-        }
-        else {
-            this.store
-                .prepare(`INSERT INTO kevin_injections
-					   (id, memory_id, fingerprint, session_id, hook, tokens, outcome)
-					 VALUES (?, ?, ?, ?, ?, ?, 'unmeasured')`)
-                .run(uuidv7(), input.memoryId, input.fingerprint, input.sessionId, input.hook, input.tokens);
-        }
-        this.metrics?.incr("injections_total", 1);
-        // v0.8.0 (K8-024 / plan §5.7) — shared-layer consumption is counted
-        // separately so the audit can tell how much of the push channel
-        // came from teammates' entries.
-        if (input.layer === "shared") {
-            this.metrics?.incr("injections_from_shared", 1);
-        }
-    }
-    /**
-     * Settles every unmeasured injection of the session: a fingerprint that
-     * failed again (as a failing tool_call) after the injection is
-     * `ineffective`, otherwise `effective`. Idempotent — only
-     * `outcome = 'unmeasured'` rows are flipped, and the recurrence charge
-     * is `MAX(recurrence_count, n)` where n = all failing calls of the
-     * fingerprint after `injected_at` (a later idle re-computes n and
-     * catches up — plan §5.1 rule 4: 3 recurrences → stale).
-     *
-     * An ineffective injection also bumps the target memory's
-     * `recurrence_count` (negative evidence, plan §5.3) and stamps
-     * `last_injected_at` (monotonically — an older row can never
-     * regress a newer injection's timestamp; the column means "most
-     * recent injection").
-     */
-    settle(sessionId) {
-        // v1.1.0 (K11-003 / plan §5.2, D11-01/D11-07) — ms-aware settle: readers
-        // prefer _ms and fall back to legacy string. Column probes are cached.
-        const hasInjMs = hasColumn(this.store, "kevin_injections", "injected_at_ms");
-        const hasToolMs = hasColumn(this.store, "tool_calls", "ts_ms");
-        const injections = (hasInjMs
-            ? this.store.prepare(`SELECT id, memory_id, fingerprint, injected_at, injected_at_ms, outcome
-						   FROM kevin_injections
-						  WHERE session_id = ?
-						  ORDER BY injected_at ASC, id ASC`)
-            : this.store.prepare(`SELECT id, memory_id, fingerprint, injected_at, outcome
-						   FROM kevin_injections
-						  WHERE session_id = ?
-						  ORDER BY injected_at ASC, id ASC`)).all(sessionId);
-        for (const inj of injections) {
-            // Same identity dimension CausalChain uses: the failing call's
-            // `error_fingerprint` (stamped by Reflector) or the legacy
-            // `fingerprint` hash.
-            // v1.1.0 — time comparison uses toMs helper (prefers _ms).
-            //
-            // BUG-003 — the exemption is now bounded to the lesson's OWN
-            // creating call (memories.metadata.origin_call_id, stamped by
-            // Reflector). The old code excluded the session's FIRST failing
-            // call of the fingerprint, which is only the creating call when
-            // the lesson was born in THIS session; a lesson created in an
-            // earlier session had its first in-session failure (a genuine
-            // post-injection recurrence) wrongly exempted, inflating
-            // precision. Memories without a tracked creating call (agent-
-            // saved, test fixtures) get no exemption: only the `ts >=
-            // injected_at` bound applies.
-            const metaRow = this.store
-                .prepare("SELECT metadata FROM memories WHERE id = ?")
-                .get(inj.memory_id);
-            const originCallId = readOriginCallId(metaRow?.metadata ?? null);
-            // v1.1.0 — heuristic: when legacy string and _ms diverge by >2s
-            // (manual UPDATE of injected_at in tests), trust the string
-            // because the ms reflects wall time at record, not the pinned
-            // fixture time. Real rows differ by <1s (second truncation).
-            const rawInjMs = inj.injected_at_ms ?? null;
-            const stringMs = inj.injected_at
-                ? Date.parse(`${inj.injected_at.replace(" ", "T")}Z`)
-                : null;
-            const injectedMs = rawInjMs !== null &&
-                stringMs !== null &&
-                !Number.isNaN(stringMs) &&
-                Math.abs(rawInjMs - stringMs) > 2000
-                ? stringMs
-                : toMs(inj.injected_at, rawInjMs);
-            // Fetch candidate failing calls for this fingerprint and filter by ms
-            const failRows = (hasToolMs
-                ? this.store.prepare(`SELECT id, ts, ts_ms FROM tool_calls
-							  WHERE session_id = ?
-							    AND success = 0
-							    AND COALESCE(error_fingerprint, fingerprint) = ?`)
-                : this.store.prepare(`SELECT id, ts FROM tool_calls
-							  WHERE session_id = ?
-							    AND success = 0
-							    AND COALESCE(error_fingerprint, fingerprint) = ?`)).all(sessionId, inj.fingerprint);
-            let n = 0;
-            for (const r of failRows) {
-                if (originCallId !== null && r.id === originCallId)
-                    continue;
-                const tsMs = toMs(r.ts, r.ts_ms ?? null);
-                if (injectedMs !== null && tsMs !== null) {
-                    if (tsMs < injectedMs)
-                        continue;
-                }
-                else {
-                    // fallback to string comparison when either side missing (legacy)
-                    if (r.ts < inj.injected_at)
-                        continue;
-                }
-                n++;
-            }
-            // v0.5.0 (K5-005 / plan §5.1, D5-01) — three-way settlement:
-            //   recurrences >= 1 → ineffective  (existing side effects unchanged)
-            //   else fixes >= 1  → effective    (a linked fix was OBSERVED)
-            //   else             → inconclusive (new majority bucket; excluded
-            //                                    from the precision denominator)
-            if (n >= 1) {
-                if (inj.outcome === "unmeasured") {
-                    this.store
-                        .prepare(`UPDATE kevin_injections SET outcome = 'ineffective'
-							  WHERE id = ?`)
-                        .run(inj.id);
-                    this.metrics?.incr("injections_ineffective", 1);
-                }
-                this.store
-                    .prepare(`UPDATE memories
-						    SET recurrence_count = MAX(recurrence_count, ?),
-						        last_injected_at = CASE
-						          WHEN last_injected_at IS NULL
-						            OR ? > last_injected_at
-						            THEN ? ELSE last_injected_at END
-						  WHERE fingerprint = ? AND id = ?`)
-                    .run(n, inj.injected_at, inj.injected_at, inj.fingerprint, inj.memory_id);
-                // v0.4.0 (K4-025 / plan §5.1 rule 4, D4-06) — recurrence
-                // expels: a fingerprint at `recurrence_count >= 3` is
-                // demoted to `status='stale'` and never injected again
-                // (only a new causal pattern — from a linked fix —
-                // re-admits the lesson, not the stale error row).
-                this.store
-                    .prepare(`UPDATE memories SET status = 'stale'
-						  WHERE id = ? AND recurrence_count >= 3`)
-                    .run(inj.memory_id);
-            }
-            else if (inj.outcome === "unmeasured") {
-                // Mirror of the recurrence predicate with the success flag
-                // inverted and the fingerprint matched on
-                // `fix_for_fingerprint` (populated by CausalChain.onSuccess,
-                // indexed by idx_tool_calls_fix_fp since migration 004). The
-                // `ts >= injected_at` bound and `session_id = ?` filter are
-                // kept; there is no `origin_call_id` exemption for fixes —
-                // a fix is not the creating call.
-                // v1.1.0 — ms-aware: fetch and filter via toMs.
-                const fixCandidates = (hasToolMs
-                    ? this.store.prepare(`SELECT ts, ts_ms FROM tool_calls
-								  WHERE session_id = ?
-								    AND success = 1
-								    AND fix_for_fingerprint = ?`)
-                    : this.store.prepare(`SELECT ts FROM tool_calls
-								  WHERE session_id = ?
-								    AND success = 1
-								    AND fix_for_fingerprint = ?`)).all(sessionId, inj.fingerprint);
-                let hasFix = false;
-                for (const fr of fixCandidates) {
-                    const tsMs = toMs(fr.ts, fr.ts_ms ?? null);
-                    if (injectedMs !== null && tsMs !== null) {
-                        if (tsMs >= injectedMs) {
-                            hasFix = true;
-                            break;
-                        }
-                    }
-                    else if (fr.ts >= inj.injected_at) {
-                        hasFix = true;
-                        break;
-                    }
-                }
-                if (hasFix) {
-                    this.store
-                        .prepare(`UPDATE kevin_injections SET outcome = 'effective'
-							  WHERE id = ?`)
-                        .run(inj.id);
-                    this.metrics?.incr("injections_effective", 1);
-                }
-                else {
-                    this.store
-                        .prepare(`UPDATE kevin_injections SET outcome = 'inconclusive'
-							  WHERE id = ?`)
-                        .run(inj.id);
-                    this.metrics?.incr("injections_inconclusive", 1);
-                }
-            }
-        }
-    }
-    /**
-     * Per-fingerprint failing tool-call counts for the session. Feeds
-     * QualityGate.canInject and the HITL suggestion block.
-     */
-    recurrencesFor(sessionId) {
-        const rows = this.store
-            .prepare(`SELECT COALESCE(error_fingerprint, fingerprint) AS fp
-				   FROM tool_calls
-				  WHERE session_id = ? AND success = 0
-				    AND (error_fingerprint IS NOT NULL OR fingerprint IS NOT NULL)`)
-            .all(sessionId);
-        const out = new Map();
-        for (const r of rows) {
-            if (!r.fp)
-                continue;
-            out.set(r.fp, (out.get(r.fp) ?? 0) + 1);
-        }
-        return out;
-    }
-    /**
-     * v0.4.0 (K4-017) — recurrence counts for the QualityGate at
-     * injection time: only failing calls that happened AFTER the
-     * fingerprint was already injected this session count. The failure
-     * that *created* a lesson is not a recurrence — it precedes any
-     * injection (plan §5.1 rule 4, same `ts >= injected_at` semantics
-     * `settle` uses).
-     */
-    postInjectionRecurrencesFor(sessionId) {
-        const rows = this.store
-            .prepare(`SELECT COALESCE(t.error_fingerprint, t.fingerprint) AS fp
-				   FROM tool_calls t
-				  WHERE t.session_id = ? AND t.success = 0
-				    AND (t.error_fingerprint IS NOT NULL OR t.fingerprint IS NOT NULL)
-				    AND t.ts >= COALESCE(
-				          (SELECT MAX(injected_at) FROM kevin_injections
-				            WHERE session_id = t.session_id
-				              AND fingerprint = COALESCE(t.error_fingerprint, t.fingerprint)),
-				          '9999-12-31')`)
-            .all(sessionId);
-        const out = new Map();
-        for (const r of rows) {
-            if (!r.fp)
-                continue;
-            out.set(r.fp, (out.get(r.fp) ?? 0) + 1);
-        }
-        return out;
-    }
-    /** Number of rows for the session not yet settled (drives tests and settle). */
-    unsettledForSession(sessionId) {
-        const row = this.store
-            .prepare(`SELECT COUNT(*) AS n FROM kevin_injections
-				  WHERE session_id = ? AND outcome = 'unmeasured'`)
-            .get(sessionId);
-        return row.n;
-    }
-    /** Latest ledger rows for a session, newest first (used by tests/tools). */
-    rowsForSession(sessionId) {
-        return this.store
-            .prepare(`SELECT id, memory_id, fingerprint, session_id, hook, tokens,
-				        injected_at, outcome
-				   FROM kevin_injections
-				  WHERE session_id = ?
-				  ORDER BY injected_at ASC, id ASC`)
-            .all(sessionId);
-    }
-    /**
-     * v0.5.0 (K5-005 / plan §8.4) — one grouped rollup over the whole
-     * ledger, zero-filled for every outcome. Consumed by `kevin_audit`.
-     */
-    outcomeCounts() {
-        const rows = this.store
-            .prepare("SELECT outcome, COUNT(*) AS n FROM kevin_injections GROUP BY outcome")
-            .all();
-        const out = {
-            unmeasured: 0,
-            effective: 0,
-            ineffective: 0,
-            inconclusive: 0,
-        };
-        for (const r of rows) {
-            out[r.outcome] = r.n;
-        }
-        return out;
-    }
-}
-// v1.1.0 — readOriginCallId deduplicated: imported from MemoryService (K11-003/K11-013)

package/dist/plugin/LessonFixer.d.ts

@@ -1,44 +0,0 @@
-/**
- * v0.4.0 (K4-014) — Deterministic fix capture (plan §5.4 / D4-07).
- *
- * Zero-cost "Fixed by:" raw material from local data: when CausalChain
- * links a success to a failing fingerprint, the linked tool_call's
- * `args_summary` becomes a deterministic fix string stored in
- * `memories.fix_args`. The default promotion path is pure local data —
- * no LLM calls (principle 14).
- */
-/** Max length of the `args_summary` embedded in a fix_args string. */
-export declare const FIX_ARGS_TRUNCATE = 120;
-export interface LinkedToolCall {
-    tool: string;
-    args_summary: string | null;
-}
-/**
- * `"bash" with args "npm i -g rg"` style. Returns null when the linked
- * call carries no args_summary (nothing to say).
- */
-export declare function extractFixArgs(call: LinkedToolCall): string | null;
-export interface EnrichInput {
-    lesson: string;
-    fixArgs: string | null;
-    originalError: string | null;
-}
-/**
- * Opt-in LLM phrasing hook (K4-015): receives the lesson, the
- * deterministic fix_args and the original error; returns a one-line
- * `Fix:` phrasing, or null to fall back to the deterministic text.
- * May be async; never runs on the failure hot path.
- */
-export type EnrichFn = (input: EnrichInput) => Promise<string | null>;
-export interface PatternLike {
-    content: string;
-    fixArgs: string | null;
-}
-/** Deterministic `Fixed by: {fix_args}` line (or "" when there is none). */
-export declare function deterministicFixLine(pattern: PatternLike): string;
-/**
- * Promotion-time fix phrasing. Default path returns the deterministic
- * `Fixed by: {fix_args}` line (or "" when there is none). When an
- * `enrichFn` is supplied and returns a phrase, that phrase wins.
- */
-export declare function enrichAtPromotion(pattern: PatternLike, enrichFn?: EnrichFn): Promise<string>;

package/dist/plugin/LessonFixer.js

@@ -1,45 +0,0 @@
-/**
- * v0.4.0 (K4-014) — Deterministic fix capture (plan §5.4 / D4-07).
- *
- * Zero-cost "Fixed by:" raw material from local data: when CausalChain
- * links a success to a failing fingerprint, the linked tool_call's
- * `args_summary` becomes a deterministic fix string stored in
- * `memories.fix_args`. The default promotion path is pure local data —
- * no LLM calls (principle 14).
- */
-/** Max length of the `args_summary` embedded in a fix_args string. */
-export const FIX_ARGS_TRUNCATE = 120;
-/**
- * `"bash" with args "npm i -g rg"` style. Returns null when the linked
- * call carries no args_summary (nothing to say).
- */
-export function extractFixArgs(call) {
-    const raw = call.args_summary?.trim();
-    if (!raw)
-        return null;
-    const truncated = raw.length > FIX_ARGS_TRUNCATE
-        ? `${raw.slice(0, FIX_ARGS_TRUNCATE)}…`
-        : raw;
-    return `${call.tool} with args "${truncated}"`;
-}
-/** Deterministic `Fixed by: {fix_args}` line (or "" when there is none). */
-export function deterministicFixLine(pattern) {
-    return pattern.fixArgs ? `Fixed by: ${pattern.fixArgs}` : "";
-}
-/**
- * Promotion-time fix phrasing. Default path returns the deterministic
- * `Fixed by: {fix_args}` line (or "" when there is none). When an
- * `enrichFn` is supplied and returns a phrase, that phrase wins.
- */
-export async function enrichAtPromotion(pattern, enrichFn) {
-    if (enrichFn) {
-        const phrased = await enrichFn({
-            lesson: pattern.content,
-            fixArgs: pattern.fixArgs,
-            originalError: null,
-        });
-        if (phrased)
-            return phrased;
-    }
-    return deterministicFixLine(pattern);
-}

package/dist/plugin/Materializer.d.ts

@@ -1,83 +0,0 @@
-import type { ArtifactWriter, WriteOutcome } from "./ArtifactWriter.js";
-import type { Store } from "./Store.js";
-/**
- * K6-017 — v0.6.0 pull — topic bundles for the pull channels (plan §5.6).
- *
- * Writes `~/.opencode-kevin/refs/<topic>.md` (one file per topic) and
- * `~/.opencode-kevin/skills/project-knowledge.md` (one file). Both go
- * through the `ArtifactWriter` — marker-scoped, atomic, hash-audited.
- * There is no direct raw file-write anywhere in this module (D6-01).
- *
- * Topic derivation is deterministic and semantic (D6-14): a topic is
- * `<type>-<dominant token>`, where the dominant token is the
- * highest-frequency non-stop-word token of the fingerprint-normalized
- * content across the memories in the group, ties broken lexicographically.
- * Topics are NEVER derived from a fingerprint prefix, and hash-like tokens
- * (hex-only, length >= 8) are excluded from the race entirely.
- *
- * Output ordering within each bundle is by memory id, matching §5.4.
- * Regeneration with unchanged inputs is a `noop` at the ArtifactWriter
- * level, so the "run twice, compare bytes" criterion holds for every
- * bundle.
- */
-export interface MaterializedBundle {
-    readonly topic: string;
-    readonly path: string;
-    readonly outcome: WriteOutcome;
-}
-export interface BundleTarget {
-    readonly topic: string;
-    readonly path: string;
-}
-export declare const SKILL_TOPIC = "project-knowledge";
-/**
- * v0.9.0 (K9-016 / plan §5.4, D9-10) — the native registration surfaces.
- * Registration replaces emission; they are never both active.
- */
-export type NativeSurface = "skill" | "reference";
-export declare class Materializer {
-    private readonly store;
-    /** `root` is injectable for tests; production defaults to ~/.opencode-kevin. */
-    private readonly 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.
-     */
-    private readonly nativeRegistered;
-    constructor(store: Store, options?: {
-        root?: string;
-    });
-    /**
-     * 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: NativeSurface, registered: boolean): void;
-    /** v0.9.0 (K9-016 / plan §5.4, D9-10) — is the surface registered natively? */
-    hasNativeRegistration(surface: NativeSurface): boolean;
-    /** The curated, active memories — the knowledge the pull channels publish. */
-    private curatedRows;
-    /** The rendered skill body over all curated memories; "" when empty. */
-    skillBody(): string;
-    /** Group rows by type, deriving each type's topic from its own content. */
-    private groupByTopic;
-    /**
-     * The pull-channel targets: the skill file plus one ref file per topic.
-     * The order is deterministic (skill first, refs by topic).
-     */
-    bundleTargets(): BundleTarget[];
-    /**
-     * 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: ArtifactWriter): MaterializedBundle[];
-}

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,
-            }),
-        }));
-    }
-}