@hatk/hatk 0.0.1-alpha.103 → 0.0.1-alpha.104

package/dist/classifiers.d.ts

@@ -0,0 +1,191 @@
+/** A typed question in the shape Clef accepts. */
+export interface ClassifierQuestion {
+    type: 'noul' | 'choice' | 'score';
+    instructions: string | Record<string, unknown> | unknown[];
+    criteria?: unknown;
+}
+/** The thing being scored: an account (by DID) or a single record. */
+export interface ClassifierSubject {
+    /** `at://` URI for a record subject; the bare DID for an account subject. */
+    uri: string;
+    did: string;
+    handle?: string | null;
+    collection?: string;
+    value?: Record<string, any>;
+}
+export interface ClassifierContext {
+    db: {
+        query: (sql: string, params?: any[]) => Promise<any[]>;
+        run: (sql: string, ...params: any[]) => Promise<void>;
+    };
+    subject: ClassifierSubject;
+}
+export interface ClassifierModule {
+    /** `account` scans every indexed repo; `record` scans rows of `collections`. */
+    subject: 'account' | 'record';
+    /** Collections to scan. Required when `subject` is `record`. */
+    collections?: string[];
+    /** The questions to ask. Answers come back under the same keys. Omit when
+     *  the classifier supplies its own `classify`. */
+    questions?: Record<string, ClassifierQuestion>;
+    /**
+     * Produce signals without asking Clef.
+     *
+     * A classifier that runs its own model — an image classifier on the host, a
+     * hash lookup, a heuristic — sets this instead of `questions`. Everything
+     * downstream is unchanged: the same thresholds, the same report, the same
+     * review card. Return a bare number for a plain score.
+     */
+    classify?: (state: Record<string, unknown>, ctx: ClassifierContext) => Promise<Record<string, number | Signal>>;
+    /**
+     * Build the model `state` for this subject. Return `null` to skip it — a
+     * skipped subject costs no tokens. Gate on whatever makes the question
+     * answerable: an account with no content cannot be judged on its content.
+     */
+    buildState: (ctx: ClassifierContext) => Promise<Record<string, unknown> | null>;
+    /**
+     * URLs of images to show the model alongside `state`, at most four. hatk
+     * fetches each and embeds it in the request, since Clef takes images inline
+     * rather than by reference.
+     *
+     * Return small renditions. Clef's context window is counted on the encoded
+     * bytes, so a full-size photo can overflow it where a 512px one never does.
+     * The state should carry whatever identifies the image — a blob CID — so
+     * that a changed image changes the fingerprint and is scored again.
+     */
+    images?: (state: Record<string, unknown>, ctx: ClassifierContext) => Promise<string[]> | string[];
+    /**
+     * Score at or above which a signal files a report. A number applies to every
+     * question; a map sets it per question. Questions absent from the map never
+     * file, though their scores are still stored and shown.
+     */
+    threshold?: number | Record<string, number>;
+    /** Label the filed report carries. A function receives the crossing signal. */
+    label?: string | ((signal: string, score: number) => string);
+}
+export declare function defineClassifier(module: ClassifierModule): {
+    /** `account` scans every indexed repo; `record` scans rows of `collections`. */
+    subject: "account" | "record";
+    /** Collections to scan. Required when `subject` is `record`. */
+    collections?: string[];
+    /** The questions to ask. Answers come back under the same keys. Omit when
+     *  the classifier supplies its own `classify`. */
+    questions?: Record<string, ClassifierQuestion>;
+    /**
+     * Produce signals without asking Clef.
+     *
+     * A classifier that runs its own model — an image classifier on the host, a
+     * hash lookup, a heuristic — sets this instead of `questions`. Everything
+     * downstream is unchanged: the same thresholds, the same report, the same
+     * review card. Return a bare number for a plain score.
+     */
+    classify?: (state: Record<string, unknown>, ctx: ClassifierContext) => Promise<Record<string, number | Signal>>;
+    /**
+     * Build the model `state` for this subject. Return `null` to skip it — a
+     * skipped subject costs no tokens. Gate on whatever makes the question
+     * answerable: an account with no content cannot be judged on its content.
+     */
+    buildState: (ctx: ClassifierContext) => Promise<Record<string, unknown> | null>;
+    /**
+     * URLs of images to show the model alongside `state`, at most four. hatk
+     * fetches each and embeds it in the request, since Clef takes images inline
+     * rather than by reference.
+     *
+     * Return small renditions. Clef's context window is counted on the encoded
+     * bytes, so a full-size photo can overflow it where a 512px one never does.
+     * The state should carry whatever identifies the image — a blob CID — so
+     * that a changed image changes the fingerprint and is scored again.
+     */
+    images?: (state: Record<string, unknown>, ctx: ClassifierContext) => Promise<string[]> | string[];
+    /**
+     * Score at or above which a signal files a report. A number applies to every
+     * question; a map sets it per question. Questions absent from the map never
+     * file, though their scores are still stored and shown.
+     */
+    threshold?: number | Record<string, number>;
+    /** Label the filed report carries. A function receives the crossing signal. */
+    label?: string | ((signal: string, score: number) => string);
+    __type: "classifiers";
+};
+interface LoadedClassifier extends ClassifierModule {
+    name: string;
+}
+/** Discover and load classifier modules from the `classifiers/` directory. */
+export declare function initClassifiers(classifiersDir: string): Promise<void>;
+/**
+ * Register a classifier directly, bypassing directory discovery.
+ *
+ * Mirrors {@link registerLabelModule}: tests and embedders that build their own
+ * module graph have no `classifiers/` directory to read.
+ */
+export declare function registerClassifier(name: string, module: ClassifierModule): void;
+/** Clear all registered classifiers (for hot-reload). */
+export declare function clearClassifiers(): void;
+/** Names of all loaded classifiers. */
+export declare function listClassifiers(): string[];
+export declare function getClassifier(name: string): LoadedClassifier | undefined;
+export interface ClefClientConfig {
+    apiToken: string;
+    model: string;
+    endpoint: string;
+}
+export declare function configureClef(config: ClefClientConfig | null): void;
+export declare function isClefConfigured(): boolean;
+/** A single answer, normalized to a 0–1 score regardless of question type. */
+export interface Signal {
+    score: number;
+    type: string;
+    /** Choice/Score only: the selected option and its confidence. */
+    choice?: string;
+    confidence?: number;
+}
+/**
+ * Ask Clef one request's worth of questions about one state.
+ *
+ * Retries on 429 and 5xx, honoring `retry-after` when the response carries one.
+ * The caller's concurrency is what keeps us under the rate limit; this only
+ * recovers the requests that still slip past it.
+ */
+export declare function askClef(state: Record<string, unknown>, questions: Record<string, ClassifierQuestion>, opts?: {
+    images?: string[];
+    attempts?: number;
+    signal?: AbortSignal;
+}): Promise<{
+    answers: Record<string, Signal>;
+    model: string;
+    inputTokens: number;
+}>;
+export interface ScanProgress {
+    /** Subjects considered. */
+    scanned: number;
+    /** Gated out by `buildState` returning null, or unchanged since the last scan. */
+    skipped: number;
+    /** Sent to the model and stored. */
+    scored: number;
+    /** Reports filed for crossing a threshold. */
+    filed: number;
+    errors: number;
+    inputTokens: number;
+    running: boolean;
+    startedAt: string;
+    finishedAt?: string;
+    error?: string;
+}
+/** Progress of the scan in flight, or the last one to finish. */
+export declare function getScanProgress(): ScanProgress | null;
+/**
+ * Score every subject a classifier applies to, storing results and filing a
+ * report for each crossing signal.
+ *
+ * Subjects whose state is unchanged since the last scan are skipped unless
+ * `force` is set, so a repeat scan costs only what actually moved.
+ */
+export declare function runScan(opts?: {
+    classifier?: string;
+    force?: boolean;
+    limit?: number;
+    concurrency?: number;
+    signal?: AbortSignal;
+}): Promise<ScanProgress>;
+export {};
+//# sourceMappingURL=classifiers.d.ts.map

package/dist/classifiers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"classifiers.d.ts","sourceRoot":"","sources":["../src/classifiers.ts"],"names":[],"mappings":"AAgDA,kDAAkD;AAClD,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAA;IACjC,YAAY,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,EAAE,CAAA;IAC1D,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,sEAAsE;AACtE,MAAM,WAAW,iBAAiB;IAChC,6EAA6E;IAC7E,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;IACX,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;CAC5B;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE;QACF,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,GAAG,EAAE,CAAC,CAAA;QACtD,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;KACtD,CAAA;IACD,OAAO,EAAE,iBAAiB,CAAA;CAC3B;AAED,MAAM,WAAW,gBAAgB;IAC/B,gFAAgF;IAChF,OAAO,EAAE,SAAS,GAAG,QAAQ,CAAA;IAC7B,gEAAgE;IAChE,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;IACtB;sDACkD;IAClD,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAA;IAC9C;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,iBAAiB,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC,CAAA;IAC/G;;;;OAIG;IACH,UAAU,EAAE,CAAC,GAAG,EAAE,iBAAiB,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,CAAA;IAC/E;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,iBAAiB,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,GAAG,MAAM,EAAE,CAAA;IACjG;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC3C,+EAA+E;IAC/E,KAAK,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC,CAAA;CAC7D;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,gBAAgB;IA3CvD,gFAAgF;aACvE,SAAS,GAAG,QAAQ;IAC7B,gEAAgE;kBAClD,MAAM,EAAE;IACtB;sDACkD;gBACtC,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC;IAC9C;;;;;;;OAOG;eACQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,iBAAiB,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC;IAC/G;;;;OAIG;gBACS,CAAC,GAAG,EAAE,iBAAiB,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC/E;;;;;;;;;OASG;aACM,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,iBAAiB,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,GAAG,MAAM,EAAE;IACjG;;;;OAIG;gBACS,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAC3C,+EAA+E;YACvE,MAAM,GAAG,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;;EAK7D;AAED,UAAU,gBAAiB,SAAQ,gBAAgB;IACjD,IAAI,EAAE,MAAM,CAAA;CACb;AAID,8EAA8E;AAC9E,wBAAsB,eAAe,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAsB3E;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAE/E;AAED,yDAAyD;AACzD,wBAAgB,gBAAgB,IAAI,IAAI,CAEvC;AAED,uCAAuC;AACvC,wBAAgB,eAAe,IAAI,MAAM,EAAE,CAE1C;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS,CAExE;AAID,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,MAAM,CAAA;CACjB;AAID,wBAAgB,aAAa,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI,GAAG,IAAI,CAEnE;AAED,wBAAgB,gBAAgB,IAAI,OAAO,CAE1C;AA8CD,8EAA8E;AAC9E,MAAM,WAAW,MAAM;IACrB,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAOD;;;;;;GAMG;AACH,wBAAsB,OAAO,CAC3B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,EAC7C,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAAO,GACxE,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC,CA2ClF;AA8BD,MAAM,WAAW,YAAY;IAC3B,2BAA2B;IAC3B,OAAO,EAAE,MAAM,CAAA;IACf,kFAAkF;IAClF,OAAO,EAAE,MAAM,CAAA;IACf,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAA;IACd,8CAA8C;IAC9C,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,WAAW,EAAE,MAAM,CAAA;IACnB,OAAO,EAAE,OAAO,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAqDD,iEAAiE;AACjE,wBAAgB,eAAe,IAAI,YAAY,GAAG,IAAI,CAErD;AAED;;;;;;GAMG;AACH,wBAAsB,OAAO,CAC3B,IAAI,GAAE;IACJ,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,MAAM,CAAC,EAAE,WAAW,CAAA;CAChB,GACL,OAAO,CAAC,YAAY,CAAC,CA+IvB"}

package/dist/classifiers.js

@@ -0,0 +1,424 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+/**
+ * Classifier system for scoring accounts and records with Clef, Cloudflare's
+ * decision model on Workers AI.
+ *
+ * A classifier is the moderation counterpart to a label rule: where a label rule
+ * decides from the record alone, a classifier asks a model a set of narrow typed
+ * questions and stores the probabilities. Nothing acts on a score — crossing a
+ * threshold files a report into the same `_reports` queue a user report lands in,
+ * so a person still makes every enforcement decision.
+ *
+ * Place classifier modules in the `classifiers/` directory.
+ *
+ * @example
+ * ```ts
+ * // classifiers/impersonation.ts
+ * import { defineClassifier } from '$hatk'
+ *
+ * export default defineClassifier({
+ *   subject: 'account',
+ *   label: 'impersonation',
+ *   threshold: 0.7,
+ *   questions: {
+ *     passing_as: {
+ *       type: 'noul',
+ *       instructions: 'Is this account trying to be mistaken for a famous person?',
+ *     },
+ *   },
+ *   async buildState({ subject, db }) {
+ *     const [p] = await db.query(`SELECT description FROM profile WHERE did = $1`, [subject.did])
+ *     return { handle: subject.handle, bio: p?.description }
+ *   },
+ * })
+ * ```
+ */
+import { resolve } from 'node:path';
+import { readdirSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { querySQL, runSQL, getSchema, upsertClassification, getClassificationFingerprints, findOpenReport, insertReport, } from "./database/db.js";
+import { log, emit } from "./logger.js";
+export function defineClassifier(module) {
+    return { __type: 'classifiers', ...module };
+}
+const classifiers = [];
+/** Discover and load classifier modules from the `classifiers/` directory. */
+export async function initClassifiers(classifiersDir) {
+    let files;
+    try {
+        files = readdirSync(classifiersDir)
+            .filter((f) => (f.endsWith('.ts') || f.endsWith('.js')) && !f.startsWith('_'))
+            .sort();
+    }
+    catch {
+        return;
+    }
+    for (const file of files) {
+        const name = file.replace(/\.(ts|js)$/, '');
+        const scriptPath = resolve(classifiersDir, file);
+        const mod = await import(__rewriteRelativeImportExtension(/* @vite-ignore */ `${scriptPath}?t=${Date.now()}`));
+        const handler = mod.default;
+        if (!handler?.buildState || !(handler.questions || handler.classify)) {
+            log(`[classifiers] skipped ${name}: needs buildState plus questions or classify`);
+            continue;
+        }
+        classifiers.push({ name, ...handler });
+        log(`[classifiers] discovered: ${name} (${handler.subject})`);
+    }
+}
+/**
+ * Register a classifier directly, bypassing directory discovery.
+ *
+ * Mirrors {@link registerLabelModule}: tests and embedders that build their own
+ * module graph have no `classifiers/` directory to read.
+ */
+export function registerClassifier(name, module) {
+    classifiers.push({ name, ...module });
+}
+/** Clear all registered classifiers (for hot-reload). */
+export function clearClassifiers() {
+    classifiers.length = 0;
+}
+/** Names of all loaded classifiers. */
+export function listClassifiers() {
+    return classifiers.map((c) => c.name);
+}
+export function getClassifier(name) {
+    return classifiers.find((c) => c.name === name);
+}
+let clef = null;
+export function configureClef(config) {
+    clef = config;
+}
+export function isClefConfigured() {
+    return clef !== null;
+}
+/** Clef's ceiling on images per request. */
+const MAX_IMAGES = 4;
+/**
+ * The longest side an image is sent at. Clef counts its context on the encoded
+ * bytes: a 1000px feed thumbnail of 200KB or more overflows the 65k window,
+ * while at 512px every image measured fit in about a thousand tokens.
+ */
+const IMAGE_EDGE = 512;
+let sharpModule;
+function loadSharp() {
+    sharpModule ??= import('sharp')
+        .then((m) => m.default)
+        .catch(() => {
+        emit('classifiers', 'resize_unavailable', { reason: 'sharp is not installed' });
+        return null;
+    });
+    return sharpModule;
+}
+/**
+ * Fetch an image and embed it as the base64 data URI Clef requires, scaled
+ * down to {@link IMAGE_EDGE}. Without sharp the original is sent, and an image
+ * too large for the context window fails that one subject.
+ */
+async function embedImage(url, signal) {
+    const res = await fetch(url, { signal });
+    if (!res.ok)
+        throw new Error(`image ${res.status}: ${url}`);
+    const type = (res.headers.get('content-type') ?? '').split(';')[0].trim();
+    if (!/^image\/(png|jpeg|webp)$/.test(type))
+        throw new Error(`image ${url} is ${type || 'untyped'}, not PNG, JPEG or WebP`);
+    const source = Buffer.from(await res.arrayBuffer());
+    const sharp = await loadSharp();
+    if (!sharp)
+        return `data:${type};base64,${source.toString('base64')}`;
+    const scaled = await sharp(source)
+        .rotate()
+        .resize({ width: IMAGE_EDGE, height: IMAGE_EDGE, fit: 'inside', withoutEnlargement: true })
+        .jpeg({ quality: 80 })
+        .toBuffer();
+    return `data:image/jpeg;base64,${scaled.toString('base64')}`;
+}
+const RETRYABLE = new Set([408, 429, 500, 502, 503, 504]);
+/** A response that a retry would only repeat: a rejected request, or the last attempt. */
+class FatalClefError extends Error {
+}
+/**
+ * Ask Clef one request's worth of questions about one state.
+ *
+ * Retries on 429 and 5xx, honoring `retry-after` when the response carries one.
+ * The caller's concurrency is what keeps us under the rate limit; this only
+ * recovers the requests that still slip past it.
+ */
+export async function askClef(state, questions, opts = {}) {
+    if (!clef)
+        throw new Error('Clef is not configured — set `clef` in hatk.config.ts');
+    const attempts = opts.attempts ?? 4;
+    const images = opts.images?.length ? opts.images : undefined;
+    const body = JSON.stringify({ state, model: clef.model, questions, ...(images ? { images } : {}) });
+    let lastError = null;
+    for (let attempt = 0; attempt < attempts; attempt++) {
+        try {
+            const res = await fetch(clef.endpoint, {
+                method: 'POST',
+                headers: { authorization: `Bearer ${clef.apiToken}`, 'content-type': 'application/json' },
+                body,
+                signal: opts.signal,
+            });
+            if (!res.ok) {
+                if (!RETRYABLE.has(res.status) || attempt === attempts - 1) {
+                    throw new FatalClefError(`Clef ${res.status}: ${(await res.text()).slice(0, 200)}`);
+                }
+                const retryAfter = Number(res.headers.get('retry-after'));
+                const waitMs = Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter * 1000 : 2 ** attempt * 500;
+                await new Promise((r) => setTimeout(r, waitMs));
+                continue;
+            }
+            // Workers AI wraps the model's output in `{ result, success, errors }`.
+            const json = (await res.json());
+            if (json.success === false)
+                throw new FatalClefError(`Clef: ${JSON.stringify(json.errors).slice(0, 200)}`);
+            const out = json.result ?? json;
+            const answers = {};
+            for (const [key, a] of Object.entries(out.answers ?? {})) {
+                answers[key] = normalizeAnswer(a);
+            }
+            return { answers, model: out.model ?? clef.model, inputTokens: out.usage?.input_tokens ?? 0 };
+        }
+        catch (err) {
+            if (err?.name === 'AbortError' || err instanceof FatalClefError)
+                throw err;
+            lastError = err;
+            if (attempt === attempts - 1)
+                break;
+            await new Promise((r) => setTimeout(r, 2 ** attempt * 500));
+        }
+    }
+    throw lastError ?? new Error('Clef request failed');
+}
+/**
+ * Collapse any answer type to one 0–1 number so a mixed question set can share a
+ * threshold. A Noul is already a probability. A Choice reports the probability
+ * of the option it picked, and a Score its position across the levels — both
+ * keep the original answer alongside, because the number alone loses which
+ * option was chosen.
+ */
+function normalizeAnswer(a) {
+    if (a?.type === 'noul')
+        return { score: a.noul ?? 0, type: 'noul' };
+    if (a?.type === 'choice') {
+        const choice = a.choice;
+        return { score: a.probabilities?.[choice] ?? 0, type: 'choice', choice, confidence: a.confidence };
+    }
+    if (a?.type === 'score') {
+        const levels = a.probabilities ? Object.keys(a.probabilities).length : 0;
+        const raw = typeof a.score === 'number' ? a.score : 0;
+        return {
+            score: levels > 1 ? raw / (levels - 1) : raw,
+            type: 'score',
+            choice: String(a.score),
+            confidence: a.confidence,
+        };
+    }
+    return { score: 0, type: a?.type ?? 'unknown' };
+}
+function thresholdFor(c, signal) {
+    if (c.threshold == null)
+        return null;
+    if (typeof c.threshold === 'number')
+        return c.threshold;
+    return c.threshold[signal] ?? null;
+}
+function labelFor(c, signal, score) {
+    if (typeof c.label === 'function')
+        return c.label(signal, score);
+    return c.label ?? 'spam';
+}
+const dbCtx = {
+    query: (sql, params) => querySQL(sql, params),
+    run: (sql, ...params) => runSQL(sql, params).then(() => undefined),
+};
+/** Every subject a classifier applies to, as `{uri, did, handle, value}`. */
+async function enumerateSubjects(c) {
+    if (c.subject === 'account') {
+        const rows = (await querySQL(`SELECT did, handle FROM _repos WHERE status = 'active'`));
+        return rows.map((r) => ({ uri: r.did, did: r.did, handle: r.handle }));
+    }
+    const out = [];
+    for (const collection of c.collections ?? []) {
+        const schema = getSchema(collection);
+        if (!schema)
+            continue;
+        const rows = (await querySQL(`SELECT * FROM ${schema.tableName}`));
+        for (const row of rows) {
+            const value = {};
+            for (const col of schema.columns) {
+                let v = row[col.name];
+                if (v === null || v === undefined)
+                    continue;
+                if (col.isJson && typeof v === 'string') {
+                    try {
+                        v = JSON.parse(v);
+                    }
+                    catch { }
+                }
+                value[col.originalName] = v;
+            }
+            out.push({ uri: row.uri, did: row.did, collection, value });
+        }
+    }
+    return out;
+}
+let current = null;
+/** Progress of the scan in flight, or the last one to finish. */
+export function getScanProgress() {
+    return current;
+}
+/**
+ * Score every subject a classifier applies to, storing results and filing a
+ * report for each crossing signal.
+ *
+ * Subjects whose state is unchanged since the last scan are skipped unless
+ * `force` is set, so a repeat scan costs only what actually moved.
+ */
+export async function runScan(opts = {}) {
+    if (current?.running)
+        throw new Error('A scan is already running');
+    const selected = opts.classifier ? classifiers.filter((c) => c.name === opts.classifier) : classifiers;
+    if (!selected.length)
+        throw new Error(opts.classifier ? `No classifier named ${opts.classifier}` : 'No classifiers');
+    // Only the classifiers that actually ask Clef need it configured. A
+    // host-local classifier runs with no API token at all.
+    if (selected.some((c) => !c.classify) && !isClefConfigured())
+        throw new Error('Clef is not configured');
+    const progress = {
+        scanned: 0,
+        skipped: 0,
+        scored: 0,
+        filed: 0,
+        errors: 0,
+        inputTokens: 0,
+        running: true,
+        startedAt: new Date().toISOString(),
+    };
+    current = progress;
+    try {
+        for (const c of selected) {
+            const subjects = await enumerateSubjects(c);
+            const seen = opts.force ? new Map() : await getClassificationFingerprints(c.name);
+            // The questions are part of what produced a score, so the fingerprint
+            // covers them as well as the state: rewording a classifier's criteria,
+            // or changing which images it sends, invalidates every score written
+            // under the old version.
+            const questionsHash = createHash('sha256')
+                .update(JSON.stringify(c.questions ?? c.classify?.toString() ?? ''))
+                .update(c.images?.toString() ?? '')
+                .digest('hex')
+                .slice(0, 16);
+            const queue = opts.limit ? subjects.slice(0, opts.limit) : subjects;
+            const concurrency = opts.concurrency ?? 8;
+            let cursor = 0;
+            const worker = async () => {
+                while (cursor < queue.length) {
+                    if (opts.signal?.aborted)
+                        return;
+                    const subject = queue[cursor++];
+                    progress.scanned++;
+                    try {
+                        const state = await c.buildState({ db: dbCtx, subject });
+                        if (!state) {
+                            progress.skipped++;
+                            continue;
+                        }
+                        const fingerprint = createHash('sha256')
+                            .update(questionsHash)
+                            .update(JSON.stringify(state))
+                            .digest('hex')
+                            .slice(0, 32);
+                        if (seen.get(subject.uri) === fingerprint) {
+                            progress.skipped++;
+                            continue;
+                        }
+                        let answers;
+                        let model;
+                        if (c.classify) {
+                            const raw = await c.classify(state, { db: dbCtx, subject });
+                            answers = Object.fromEntries(Object.entries(raw).map(([k, v]) => [k, typeof v === 'number' ? { score: v, type: 'local' } : v]));
+                            model = `local:${c.name}`;
+                        }
+                        else {
+                            const urls = c.images ? (await c.images(state, { db: dbCtx, subject })).slice(0, MAX_IMAGES) : [];
+                            const images = await Promise.all(urls.map((u) => embedImage(u, opts.signal)));
+                            const res = await askClef(state, c.questions, { images, signal: opts.signal });
+                            answers = res.answers;
+                            model = res.model;
+                            progress.inputTokens += res.inputTokens;
+                        }
+                        let topSignal = null;
+                        let topScore = 0;
+                        for (const [name, sig] of Object.entries(answers)) {
+                            if (sig.score > topScore) {
+                                topScore = sig.score;
+                                topSignal = name;
+                            }
+                        }
+                        await upsertClassification({
+                            subjectUri: subject.uri,
+                            subjectDid: subject.did,
+                            classifier: c.name,
+                            signals: answers,
+                            state,
+                            topSignal,
+                            topScore,
+                            fingerprint,
+                            model,
+                        });
+                        progress.scored++;
+                        // File on the highest-scoring signal that crosses its own threshold —
+                        // a second report for the same subject would only split the review.
+                        let crossing = null;
+                        for (const [name, sig] of Object.entries(answers)) {
+                            const t = thresholdFor(c, name);
+                            if (t != null && sig.score >= t && (!crossing || sig.score > crossing.score)) {
+                                crossing = { signal: name, score: sig.score };
+                            }
+                        }
+                        if (crossing) {
+                            const label = labelFor(c, crossing.signal, crossing.score);
+                            if (!(await findOpenReport(subject.uri, label))) {
+                                await insertReport({
+                                    subjectUri: subject.uri,
+                                    subjectDid: subject.did,
+                                    label,
+                                    reason: `${c.name}: ${crossing.signal} ${crossing.score.toFixed(2)}`,
+                                    reportedBy: `system:${c.name}`,
+                                });
+                                progress.filed++;
+                            }
+                        }
+                    }
+                    catch (err) {
+                        if (err?.name === 'AbortError')
+                            return;
+                        progress.errors++;
+                        emit('classifiers', 'scan_error', { classifier: c.name, subject: subject.uri, error: err.message });
+                    }
+                }
+            };
+            await Promise.all(Array.from({ length: Math.min(concurrency, queue.length) }, worker));
+        }
+    }
+    catch (err) {
+        progress.error = err.message;
+        throw err;
+    }
+    finally {
+        progress.running = false;
+        progress.finishedAt = new Date().toISOString();
+        log(`[classifiers] scan: ${progress.scored} scored, ${progress.skipped} skipped, ` +
+            `${progress.filed} filed, ${progress.errors} errors, ${progress.inputTokens} tokens`);
+    }
+    return progress;
+}

package/dist/cli.js

@@ -443,6 +443,7 @@ else if (command === 'generate') {
         out += `export { defineSetup } from '@hatk/hatk/setup'\n`;
         out += `export { defineHook } from '@hatk/hatk/hooks'\n`;
         out += `export { defineLabel } from '@hatk/hatk/labels'\n`;
+        out += `export { defineClassifier } from '@hatk/hatk/classifiers'\n`;
         out += `export { defineOG } from '@hatk/hatk/opengraph'\n`;
         out += `export { defineRenderer } from '@hatk/hatk/renderer'\n`;
         out += `export type Ctx<K extends keyof XrpcSchema & keyof Registry> = XrpcContext<\n`;

package/dist/config.d.ts

@@ -171,9 +171,24 @@ export interface HatkConfig {
     push: PushConfig | null;
     admins: string[];
     spaces: SpacesConfig | null;
+    clef: ClefConfig | null;
+}
+/**
+ * Clef access for the classifier system, through Workers AI. Without it,
+ * classifiers load but no scan can run. The account and token are read from
+ * `CLOUDFLARE_ACCOUNT_ID` and `CLOUDFLARE_AI_TOKEN` in preference to the config
+ * file, so neither need be committed. The token needs Workers AI access and
+ * nothing else; `CLOUDFLARE_API_TOKEN` is deliberately not read, since on a host
+ * that also manages DNS it is the token with zone write.
+ */
+export interface ClefConfig {
+    accountId: string;
+    apiToken: string;
+    /** `clef` or `clef-flash`. Thresholds tuned on one do not carry to the other. */
+    model: 'clef' | 'clef-flash';
 }
 /** Input type for defineConfig — fields that have defaults are optional. */
-export type HatkConfigInput = Partial<Omit<HatkConfig, 'oauth' | 'backfill' | 'push' | 'cdn' | 'jetstream' | 'spaces'>> & {
+export type HatkConfigInput = Partial<Omit<HatkConfig, 'oauth' | 'backfill' | 'push' | 'cdn' | 'jetstream' | 'spaces' | 'clef'>> & {
     cdn?: CdnConfig | null;
     oauth?: (Partial<OAuthConfig> & {
         clients: OAuthClientConfig[];
@@ -182,6 +197,7 @@ export type HatkConfigInput = Partial<Omit<HatkConfig, 'oauth' | 'backfill' | 'p
     push?: PushConfig | null;
     jetstream?: JetstreamConfig | null;
     spaces?: SpacesConfig | null;
+    clef?: Partial<ClefConfig> | null;
 };
 /** Identity function that provides type inference for hatk config files. */
 export declare function defineConfig(config: HatkConfigInput): HatkConfigInput;