@they-juanreina/compost-cli 0.1.2 → 0.1.4

package/dist/lib/agreement.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Human↔machine intercoder agreement (§4).
+ *
+ * compost's *native* workflow produces endorse/reject decisions, which are
+ * reactive (the human sees the AI code first) — a κ computed on that violates κ's
+ * independence assumption. So legitimate agreement requires INDEPENDENT double
+ * coding: a researcher codes a sampled highlight set against the shared codebook
+ * WITHOUT seeing the machine's codes (`compost recode --blind`), and we compare
+ * those blind human codings to the machine codings on the doubly-coded units.
+ *
+ * A unit (highlight) can carry multiple codes, so we model each (unit, code) as a
+ * binary present/absent decision and compute, over the doubly-coded set:
+ *  - Cohen's κ per code and pooled over all (unit, code) cells (2 coders),
+ *  - Krippendorff's nominal α over the pooled cells (cross-check; handles the
+ *    general case).
+ */
+export type Coder = 'human' | 'machine';
+/** One coder asserting one code applies to one unit (highlight). */
+export interface Coding {
+    coder: Coder;
+    unit: string;
+    code: string;
+}
+export interface KappaResult {
+    kappa: number | null;
+    po: number;
+    pe: number;
+    n: number;
+}
+export interface PerCodeAgreement {
+    code: string;
+    kappa: number | null;
+    support: number;
+}
+export interface AgreementReport {
+    status: 'ok' | 'insufficient';
+    doubly_coded_units: number;
+    codes: number;
+    per_code: PerCodeAgreement[];
+    pooled_kappa: number | null;
+    krippendorff_alpha: number | null;
+    interpretation: string;
+    excluded_unnamed_machine_codes: number;
+    note?: string;
+}
+/** Cohen's κ for a single binary variable across paired ratings. */
+export declare function cohensKappaBinary(a: boolean[], b: boolean[]): KappaResult;
+/**
+ * Krippendorff's α (nominal metric) over a units × coders matrix. Cells may be
+ * null (a coder didn't code that unit). Units with fewer than two values are
+ * dropped (not pairable). General coincidence-matrix algorithm.
+ */
+export declare function krippendorffAlphaNominal(units: Array<Array<string | null>>): number | null;
+export interface AgreementOptions {
+    /** Minimum doubly-coded units below which κ is statistical noise. */
+    minUnits?: number;
+    excludedUnnamedMachineCodes?: number;
+}
+/**
+ * Compute agreement from a flat list of (coder, unit, code) codings. Only units
+ * coded by BOTH coders count (the doubly-coded set); the codebook is the union of
+ * codes either coder used on those units.
+ */
+export declare function computeAgreement(codings: Coding[], opts?: AgreementOptions): AgreementReport;
+/**
+ * Extract codings from a seed's event log. Machine codings come from named `code`
+ * create events (actor ai/agent) via their `evidence` highlight ids; unnamed
+ * cluster codes (similarity-scanner `members`) have no shared label and are
+ * excluded (counted, never silently dropped). Human codings come from blind
+ * `coding` link events (actor researcher, payload.blind === true). Artifacts with
+ * a reject/unlink event are excluded.
+ */
+export declare function readCodings(eventsDbPath: string): {
+    codings: Coding[];
+    excludedUnnamedMachineCodes: number;
+};
+//# sourceMappingURL=agreement.d.ts.map

package/dist/lib/agreement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agreement.d.ts","sourceRoot":"","sources":["../../src/lib/agreement.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,MAAM,KAAK,GAAG,OAAO,GAAG,SAAS,CAAA;AAEvC,oEAAoE;AACpE,MAAM,WAAW,MAAM;IACrB,KAAK,EAAE,KAAK,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;CACb;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,EAAE,EAAE,MAAM,CAAA;IACV,EAAE,EAAE,MAAM,CAAA;IACV,CAAC,EAAE,MAAM,CAAA;CACV;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,IAAI,GAAG,cAAc,CAAA;IAC7B,kBAAkB,EAAE,MAAM,CAAA;IAC1B,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,gBAAgB,EAAE,CAAA;IAC5B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAA;IACjC,cAAc,EAAE,MAAM,CAAA;IACtB,8BAA8B,EAAE,MAAM,CAAA;IACtC,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAID,oEAAoE;AACpE,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,OAAO,EAAE,EAAE,CAAC,EAAE,OAAO,EAAE,GAAG,WAAW,CAuBzE;AAID;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC,GAAG,MAAM,GAAG,IAAI,CAiD1F;AAcD,MAAM,WAAW,gBAAgB;IAC/B,qEAAqE;IACrE,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,2BAA2B,CAAC,EAAE,MAAM,CAAA;CACrC;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,IAAI,GAAE,gBAAqB,GAAG,eAAe,CA8EhG;AAUD;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,YAAY,EAAE,MAAM,GAAG;IACjD,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,2BAA2B,EAAE,MAAM,CAAA;CACpC,CAuDA"}

package/dist/lib/agreement.js

@@ -0,0 +1,261 @@
+import { existsSync } from 'node:fs';
+import Database from 'better-sqlite3';
+import { CompostError } from '../errors.js';
+// ---------------------------------------------------------------- κ (binary)
+/** Cohen's κ for a single binary variable across paired ratings. */
+export function cohensKappaBinary(a, b) {
+    if (a.length !== b.length)
+        throw new Error('cohensKappaBinary: rating arrays differ in length');
+    const n = a.length;
+    if (n === 0)
+        return { kappa: null, po: 0, pe: 0, n: 0 };
+    let n11 = 0;
+    let n00 = 0;
+    let aTrue = 0;
+    let bTrue = 0;
+    for (let i = 0; i < n; i++) {
+        if (a[i])
+            aTrue++;
+        if (b[i])
+            bTrue++;
+        if (a[i] && b[i])
+            n11++;
+        if (!a[i] && !b[i])
+            n00++;
+    }
+    const po = (n11 + n00) / n;
+    const pYesA = aTrue / n;
+    const pYesB = bTrue / n;
+    const pe = pYesA * pYesB + (1 - pYesA) * (1 - pYesB);
+    if (1 - pe === 0) {
+        // Degenerate: both marginals saturated. κ is conventionally 1 iff perfect.
+        return { kappa: po === 1 ? 1 : 0, po, pe, n };
+    }
+    return { kappa: (po - pe) / (1 - pe), po, pe, n };
+}
+// ------------------------------------------------- Krippendorff α (nominal)
+/**
+ * Krippendorff's α (nominal metric) over a units × coders matrix. Cells may be
+ * null (a coder didn't code that unit). Units with fewer than two values are
+ * dropped (not pairable). General coincidence-matrix algorithm.
+ */
+export function krippendorffAlphaNominal(units) {
+    // Coincidence matrix o[c][k] and value marginals.
+    const o = new Map();
+    const bump = (c, k, by) => {
+        if (!o.has(c))
+            o.set(c, new Map());
+        const row = o.get(c);
+        row.set(k, (row.get(k) ?? 0) + by);
+    };
+    for (const unit of units) {
+        const vals = unit.filter((v) => v !== null);
+        const m = vals.length;
+        if (m < 2)
+            continue;
+        for (let i = 0; i < m; i++) {
+            for (let j = 0; j < m; j++) {
+                if (i === j)
+                    continue;
+                bump(vals[i], vals[j], 1 / (m - 1));
+            }
+        }
+    }
+    const values = [...o.keys()];
+    let n = 0;
+    const marginal = new Map();
+    for (const c of values) {
+        let rowSum = 0;
+        for (const k of values)
+            rowSum += o.get(c)?.get(k) ?? 0;
+        marginal.set(c, rowSum);
+        n += rowSum;
+    }
+    if (n < 2)
+        return null;
+    // Observed disagreement (nominal δ = 1 when c≠k).
+    let Do = 0;
+    for (const c of values) {
+        for (const k of values) {
+            if (c === k)
+                continue;
+            Do += o.get(c)?.get(k) ?? 0;
+        }
+    }
+    Do /= n;
+    // Expected disagreement.
+    let De = 0;
+    for (const c of values) {
+        for (const k of values) {
+            if (c === k)
+                continue;
+            De += marginal.get(c) * marginal.get(k);
+        }
+    }
+    De /= n * (n - 1);
+    if (De === 0)
+        return Do === 0 ? 1 : 0;
+    return 1 - Do / De;
+}
+// ------------------------------------------------------- agreement over codings
+function landisKoch(k) {
+    if (k === null)
+        return 'undefined';
+    if (k < 0)
+        return 'poor (worse than chance)';
+    if (k <= 0.2)
+        return 'slight';
+    if (k <= 0.4)
+        return 'fair';
+    if (k <= 0.6)
+        return 'moderate';
+    if (k <= 0.8)
+        return 'substantial';
+    return 'almost perfect';
+}
+/**
+ * Compute agreement from a flat list of (coder, unit, code) codings. Only units
+ * coded by BOTH coders count (the doubly-coded set); the codebook is the union of
+ * codes either coder used on those units.
+ */
+export function computeAgreement(codings, opts = {}) {
+    const minUnits = opts.minUnits ?? 10;
+    const excluded = opts.excludedUnnamedMachineCodes ?? 0;
+    const byCoderUnit = {
+        human: new Map(),
+        machine: new Map(),
+    };
+    const allCodes = new Set();
+    for (const { coder, unit, code } of codings) {
+        if (!byCoderUnit[coder].has(unit))
+            byCoderUnit[coder].set(unit, new Set());
+        byCoderUnit[coder].get(unit)?.add(code);
+        allCodes.add(code);
+    }
+    const doublyCoded = [...byCoderUnit.human.keys()].filter((u) => byCoderUnit.machine.has(u)).sort();
+    const codes = [...allCodes].sort();
+    const base = {
+        doubly_coded_units: doublyCoded.length,
+        codes: codes.length,
+        excluded_unnamed_machine_codes: excluded,
+    };
+    if (doublyCoded.length < minUnits) {
+        return {
+            status: 'insufficient',
+            ...base,
+            per_code: [],
+            pooled_kappa: null,
+            krippendorff_alpha: null,
+            interpretation: 'undefined',
+            note: `Only ${doublyCoded.length} doubly-coded unit(s); need ≥ ${minUnits} for a meaningful κ. Code more highlights with \`compost recode --blind\`.`,
+        };
+    }
+    const has = (coder, unit, code) => byCoderUnit[coder].get(unit)?.has(code) ?? false;
+    // Per-code binary κ.
+    const perCode = [];
+    for (const code of codes) {
+        const a = [];
+        const b = [];
+        let support = 0;
+        for (const u of doublyCoded) {
+            const h = has('human', u, code);
+            const m = has('machine', u, code);
+            a.push(h);
+            b.push(m);
+            if (h || m)
+                support++;
+        }
+        perCode.push({ code, kappa: cohensKappaBinary(a, b).kappa, support });
+    }
+    // Pooled κ over every (unit, code) cell, and α as a cross-check on the same cells.
+    const pooledA = [];
+    const pooledB = [];
+    const alphaUnits = [];
+    for (const u of doublyCoded) {
+        for (const code of codes) {
+            const h = has('human', u, code);
+            const m = has('machine', u, code);
+            pooledA.push(h);
+            pooledB.push(m);
+            alphaUnits.push([h ? 'present' : 'absent', m ? 'present' : 'absent']);
+        }
+    }
+    const pooled = cohensKappaBinary(pooledA, pooledB).kappa;
+    return {
+        status: 'ok',
+        ...base,
+        per_code: perCode,
+        pooled_kappa: pooled,
+        krippendorff_alpha: krippendorffAlphaNominal(alphaUnits),
+        interpretation: landisKoch(pooled),
+    };
+}
+/**
+ * Extract codings from a seed's event log. Machine codings come from named `code`
+ * create events (actor ai/agent) via their `evidence` highlight ids; unnamed
+ * cluster codes (similarity-scanner `members`) have no shared label and are
+ * excluded (counted, never silently dropped). Human codings come from blind
+ * `coding` link events (actor researcher, payload.blind === true). Artifacts with
+ * a reject/unlink event are excluded.
+ */
+export function readCodings(eventsDbPath) {
+    if (!existsSync(eventsDbPath)) {
+        throw new CompostError('FILE_NOT_FOUND', `No events.sqlite at ${eventsDbPath}`);
+    }
+    const db = new Database(eventsDbPath, { readonly: true, fileMustExist: true });
+    try {
+        const archived = new Set(db
+            .prepare("SELECT DISTINCT artifact_id FROM events WHERE action IN ('reject','unlink')")
+            .all().map((r) => r.artifact_id));
+        const codings = [];
+        let excludedUnnamed = 0;
+        const machineRows = db
+            .prepare("SELECT artifact_id, actor_type, payload FROM events WHERE action='create' AND artifact_kind='code' AND actor_type IN ('ai','agent')")
+            .all();
+        for (const row of machineRows) {
+            if (archived.has(row.artifact_id))
+                continue;
+            const p = safeParse(row.payload);
+            const code = typeof p.name === 'string' ? p.name : undefined;
+            const units = (p.evidence ?? p.members);
+            if (code === undefined) {
+                if (Array.isArray(units) && units.length > 0)
+                    excludedUnnamed++;
+                continue;
+            }
+            if (!Array.isArray(units))
+                continue;
+            for (const u of units) {
+                if (typeof u === 'string')
+                    codings.push({ coder: 'machine', unit: u, code });
+            }
+        }
+        const humanRows = db
+            .prepare("SELECT artifact_id, actor_type, payload FROM events WHERE action='link' AND artifact_kind='coding' AND actor_type='researcher'")
+            .all();
+        for (const row of humanRows) {
+            if (archived.has(row.artifact_id))
+                continue;
+            const p = safeParse(row.payload);
+            if (p.blind !== true)
+                continue;
+            if (typeof p.code === 'string' && typeof p.highlight === 'string') {
+                codings.push({ coder: 'human', unit: p.highlight, code: p.code });
+            }
+        }
+        return { codings, excludedUnnamedMachineCodes: excludedUnnamed };
+    }
+    finally {
+        db.close();
+    }
+}
+function safeParse(s) {
+    try {
+        const v = JSON.parse(s);
+        return v !== null && typeof v === 'object' ? v : {};
+    }
+    catch {
+        return {};
+    }
+}
+//# sourceMappingURL=agreement.js.map

package/dist/lib/agreement.js.map

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

package/dist/lib/artifacts.d.ts

@@ -1,5 +1,5 @@
-import Database from 'better-sqlite3';
-import { type Author } from './events.js';
+import type Database from 'better-sqlite3';
+import { type AiInputBundle, type Author } from './events.js';
 export interface CreatedArtifact {
     id: string;
     artifact_id: string;
@@ -12,6 +12,7 @@ export interface CreateHighlightInput {
     span: [number, number];
     text: string;
     author: Author;
+    inputs?: AiInputBundle;
 }
 export declare function createHighlight(seedPath: string, input: CreateHighlightInput): CreatedArtifact;
 export interface CreateCodeInput {
@@ -19,6 +20,7 @@ export interface CreateCodeInput {
     definition: string;
     evidence?: string[];
     author: Author;
+    inputs?: AiInputBundle;
 }
 export declare function createCode(seedPath: string, input: CreateCodeInput): CreatedArtifact;
 export interface CreateThemeInput {
@@ -26,11 +28,14 @@ export interface CreateThemeInput {
     summary: string;
     codes?: string[];
     author: Author;
+    inputs?: AiInputBundle;
 }
 export declare function createTheme(seedPath: string, input: CreateThemeInput): CreatedArtifact;
 interface CreateEventRow {
     id: string;
     artifact_kind: string;
+    /** actor_id of the create event — used to refuse a self-endorse (#236). */
+    actor_id: string;
 }
 /**
  * Human-id form for an artifact ref: `H-NNN`, `C-slug`, `T-slug` — the id
@@ -58,6 +63,34 @@ export declare function endorseArtifact(seedPath: string, artifactRef: string, r
     parent_event_id: string;
     already_endorsed?: true;
 };
+/**
+ * Resolve an artifact ref to its create event, then emit a researcher reject
+ * chaining the artifact's latest event. Reject archives (current_state is
+ * preserved for audit) — the three-actor model's "delete", where nothing is
+ * ever truly removed. Idempotent: a second reject by the same researcher is a
+ * no-op returning the existing reject.
+ */
+export declare function rejectArtifact(seedPath: string, artifactRef: string, researcherId: string, note?: string): {
+    artifact_id: string;
+    reject_event_id: string;
+    parent_event_id: string;
+    already_rejected?: true;
+};
+/**
+ * Resolve an artifact ref, then emit a field-level update chaining the latest
+ * event. The event log records `{ field, before, after }` so blame shows what
+ * changed. `before` is best-effort context for the audit trail; the reducer
+ * applies only `after`.
+ */
+export declare function updateArtifact(seedPath: string, artifactRef: string, patch: {
+    field: string;
+    before?: unknown;
+    after: unknown;
+}, author: Author): {
+    artifact_id: string;
+    update_event_id: string;
+    parent_event_id: string;
+};
 /** Read the configured researcher identity: COMPOST_USER env, else fallback. */
 export declare function defaultResearcherId(): string;
 export {};

package/dist/lib/artifacts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"artifacts.d.ts","sourceRoot":"","sources":["../../src/lib/artifacts.ts"],"names":[],"mappings":"AAGA,OAAO,QAAQ,MAAM,gBAAgB,CAAA;AAGrC,OAAO,EAAE,KAAK,MAAM,EAAuD,MAAM,aAAa,CAAA;AAE9F,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAA;IACV,WAAW,EAAE,MAAM,CAAA;IACnB,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,MAAM,CAAA;CACjB;AA8ED,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,CAAA;IACjB,WAAW,EAAE,MAAM,CAAA;IACnB,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACtB,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;CACf;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,oBAAoB,GAAG,eAAe,CA+B9F;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAA;IACZ,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;IACnB,MAAM,EAAE,MAAM,CAAA;CACf;AAED,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,GAAG,eAAe,CA2BpF;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;CACf;AAED,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,gBAAgB,GAAG,eAAe,CA4BtF;AAID,UAAU,cAAc;IACtB,EAAE,EAAE,MAAM,CAAA;IACV,aAAa,EAAE,MAAM,CAAA;CACtB;AAED;;;;;GAKG;AACH,eAAO,MAAM,YAAY,QAA2B,CAAA;AAEpD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,GAAG,EAAE,MAAM,GACV,CAAC,cAAc,GAAG;IAAE,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC,GAAG,SAAS,CAOxD;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,GACnB;IACD,WAAW,EAAE,MAAM,CAAA;IACnB,gBAAgB,EAAE,MAAM,CAAA;IACxB,eAAe,EAAE,MAAM,CAAA;IACvB,gBAAgB,CAAC,EAAE,IAAI,CAAA;CACxB,CAmFA;AAED,gFAAgF;AAChF,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C"}
+{"version":3,"file":"artifacts.d.ts","sourceRoot":"","sources":["../../src/lib/artifacts.ts"],"names":[],"mappings":"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"}