@hatk/hatk 0.0.1-alpha.95 → 0.0.1-alpha.97

package/dist/classifiers.d.ts

@@ -0,0 +1,168 @@
+/** A typed question in the shape the System One API 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 a System One model.
+     *
+     * 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>;
+    /**
+     * 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 a System One model.
+     *
+     * 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>;
+    /**
+     * 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 SystemOneConfig {
+    apiKey: string;
+    model: string;
+    endpoint: string;
+}
+export declare function configureSystemOne(config: SystemOneConfig | null): void;
+export declare function isSystemOneConfigured(): 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 the model 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 askSystemOne(state: Record<string, unknown>, questions: Record<string, ClassifierQuestion>, opts?: {
+    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":"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"}

package/dist/classifiers.js

@@ -0,0 +1,370 @@
+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 a System One model.
+ *
+ * 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 systemOne = null;
+export function configureSystemOne(config) {
+    systemOne = config;
+}
+export function isSystemOneConfigured() {
+    return systemOne !== null;
+}
+const RETRYABLE = new Set([408, 429, 500, 502, 503, 504]);
+/**
+ * Ask the model 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 askSystemOne(state, questions, opts = {}) {
+    if (!systemOne)
+        throw new Error('System One is not configured — set `typesafe` in hatk.config.ts');
+    const attempts = opts.attempts ?? 4;
+    const body = JSON.stringify({ state, model: systemOne.model, questions });
+    let lastError = null;
+    for (let attempt = 0; attempt < attempts; attempt++) {
+        try {
+            const res = await fetch(systemOne.endpoint, {
+                method: 'POST',
+                headers: { authorization: `Bearer ${systemOne.apiKey}`, 'content-type': 'application/json' },
+                body,
+                signal: opts.signal,
+            });
+            if (!res.ok) {
+                if (!RETRYABLE.has(res.status) || attempt === attempts - 1) {
+                    throw new Error(`System One ${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;
+            }
+            const json = (await res.json());
+            const answers = {};
+            for (const [key, a] of Object.entries(json.answers ?? {})) {
+                answers[key] = normalizeAnswer(a);
+            }
+            return { answers, model: json.model ?? systemOne.model, inputTokens: json.usage?.input_tokens ?? 0 };
+        }
+        catch (err) {
+            if (err?.name === 'AbortError')
+                throw err;
+            lastError = err;
+            if (attempt === attempts - 1)
+                break;
+            await new Promise((r) => setTimeout(r, 2 ** attempt * 500));
+        }
+    }
+    throw lastError ?? new Error('System One 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 a model need one configured. A
+    // host-local classifier runs with no API key at all.
+    if (selected.some((c) => !c.classify) && !isSystemOneConfigured())
+        throw new Error('System One 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
+            // invalidates every score written under the old wording.
+            const questionsHash = createHash('sha256')
+                .update(JSON.stringify(c.questions ?? c.classify?.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 res = await askSystemOne(state, c.questions, { 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,21 @@ export interface HatkConfig {
     push: PushConfig | null;
     admins: string[];
     spaces: SpacesConfig | null;
+    typesafe: TypeSafeConfig | null;
+}
+/**
+ * System One access for the classifier system. Without it, classifiers load but
+ * no scan can run. The key is read from `TYPESAFE_API_KEY` in preference to the
+ * config file, so it need not be committed.
+ */
+export interface TypeSafeConfig {
+    apiKey: string;
+    /** Model name or alias. Pin a version to keep tuned thresholds stable. */
+    model: string;
+    endpoint: string;
 }
 /** 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' | 'typesafe'>> & {
     cdn?: CdnConfig | null;
     oauth?: (Partial<OAuthConfig> & {
         clients: OAuthClientConfig[];
@@ -182,6 +194,7 @@ export type HatkConfigInput = Partial<Omit<HatkConfig, 'oauth' | 'backfill' | 'p
     push?: PushConfig | null;
     jetstream?: JetstreamConfig | null;
     spaces?: SpacesConfig | null;
+    typesafe?: Partial<TypeSafeConfig> | null;
 };
 /** Identity function that provides type inference for hatk config files. */
 export declare function defineConfig(config: HatkConfigInput): HatkConfigInput;

package/dist/config.d.ts.map

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

package/dist/config.js

@@ -69,6 +69,17 @@ export async function loadConfig(configPath) {
         oauth: null,
         push: parsed.push || null,
         admins: env.ADMINS ? env.ADMINS.split(',').map((s) => s.trim()) : parsed.admins || [],
+        typesafe: (() => {
+            const raw = parsed.typesafe;
+            const apiKey = env.TYPESAFE_API_KEY || raw?.apiKey;
+            if (!apiKey)
+                return null;
+            return {
+                apiKey,
+                model: env.TYPESAFE_MODEL || raw?.model || 'jev-latest',
+                endpoint: env.TYPESAFE_ENDPOINT || raw?.endpoint || 'https://api.typesafe.ai/v1/systemone',
+            };
+        })(),
         spaces: parsed.spaces
             ? {
                 types: parsed.spaces.types || [],