pi-jev-wiki 0.2.0

package/src/git.ts

@@ -0,0 +1,69 @@
+/**
+ * Minimal git helpers for change-driven wiki invalidation.
+ * Uses child_process directly so the logic is testable without the pi runtime.
+ */
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const run = promisify(execFile);
+
+export interface GitResult {
+	code: number;
+	stdout: string;
+	stderr: string;
+}
+
+export async function git(cwd: string, args: string[]): Promise<GitResult> {
+	try {
+		const { stdout, stderr } = await run("git", ["-C", cwd, ...args], { maxBuffer: 20 * 1024 * 1024 });
+		return { code: 0, stdout, stderr };
+	} catch (error) {
+		const failure = error as { code?: number; stdout?: string; stderr?: string; message?: string };
+		return {
+			code: typeof failure.code === "number" ? failure.code : 1,
+			stdout: failure.stdout ?? "",
+			stderr: failure.stderr ?? failure.message ?? String(error),
+		};
+	}
+}
+
+export async function isGitRepo(cwd: string): Promise<boolean> {
+	const result = await git(cwd, ["rev-parse", "--is-inside-work-tree"]);
+	return result.code === 0 && result.stdout.trim() === "true";
+}
+
+export async function headCommit(cwd: string): Promise<string | undefined> {
+	const result = await git(cwd, ["rev-parse", "HEAD"]);
+	return result.code === 0 ? result.stdout.trim() : undefined;
+}
+
+export async function changedFiles(cwd: string, from: string, to = "HEAD"): Promise<string[]> {
+	const result = await git(cwd, ["diff", "--name-only", "--diff-filter=ACMR", `${from}..${to}`]);
+	if (result.code !== 0) return [];
+	return result.stdout
+		.split(/\r?\n/)
+		.map((line) => line.trim())
+		.filter(Boolean)
+		.map((line) => line.split("\\").join("/"));
+}
+
+export async function diffForFiles(cwd: string, from: string, to: string, files: string[], maxChars: number): Promise<string> {
+	if (files.length === 0) return "";
+	const result = await git(cwd, ["diff", "--no-color", "--unified=3", `${from}..${to}`, "--", ...files]);
+	if (result.code !== 0) return "";
+	return result.stdout.length > maxChars ? `${result.stdout.slice(0, maxChars)}\n[... diff truncated ...]` : result.stdout;
+}
+
+/** Exact path, directory prefix, or a simple `*` glob. */
+export function fileMatches(changedPath: string, pattern: string): boolean {
+	const changed = changedPath.split("\\").join("/");
+	const candidate = pattern.split("\\").join("/").replace(/^\.\//, "");
+	if (!candidate) return false;
+	if (candidate.includes("*")) {
+		const regex = new RegExp(`^${candidate.split("*").map((part) => part.replace(/[.+?^${}()|[\]\\]/g, "\\$&")).join(".*")}$`);
+		return regex.test(changed);
+	}
+	if (changed === candidate) return true;
+	const prefix = candidate.endsWith("/") ? candidate : `${candidate}/`;
+	return changed.startsWith(prefix);
+}

package/src/grounding.ts

@@ -0,0 +1,46 @@
+/**
+ * Writer grounding: extract load-bearing literals from generated page bodies
+ * (numbers, URLs, version strings) and check them against the evidence the
+ * writer was given. Anything absent is flagged for review — this catches the
+ * characteristic failure of generative writing: plausible invented specifics.
+ */
+
+export interface LiteralCheck {
+	literals: string[];
+	missing: string[];
+}
+
+const LITERAL_PATTERNS: RegExp[] = [
+	/\b\d+(?:[.,]\d+)*(?:\s?(?:ms|s|m|h|kb|mb|gb|tok|tokens|%)|(?:\s?(?:million|billion)))?\b/g,
+	/https?:\/\/[^\s)"'\]]+/g,
+	/\bv?\d+\.\d+(?:\.\d+)?\b/g,
+];
+
+function normalizeNumber(value: string): string {
+	return value.replace(/[,\s]/g, "").toLowerCase();
+}
+
+/** Extract literals worth verifying; single digits and years are ignored as noise. */
+export function extractLiterals(body: string): string[] {
+	const withoutCode = body.replace(/```[\s\S]*?```/g, " ");
+	const found = new Set<string>();
+	for (const pattern of LITERAL_PATTERNS) {
+		for (const match of withoutCode.matchAll(pattern)) {
+			const value = match[0].trim();
+			if (/^\d$/.test(value)) continue;
+			if (/^(19|20)\d{2}$/.test(value)) continue;
+			found.add(value);
+		}
+	}
+	return [...found];
+}
+
+export function checkLiterals(body: string, evidence: string): LiteralCheck {
+	const literals = extractLiterals(body);
+	const haystack = evidence.toLowerCase();
+	const missing = literals.filter((literal) => {
+		const candidates = [literal.toLowerCase(), normalizeNumber(literal)];
+		return !candidates.some((candidate) => haystack.includes(candidate));
+	});
+	return { literals, missing };
+}

package/src/jev.ts

@@ -0,0 +1,207 @@
+/**
+ * Minimal TypeSafe / Jev client.
+ *
+ * Endpoint contract (native schema):
+ *   POST {baseUrl}  Authorization: Bearer <key>
+ *   { model, state, questions: { key: Question } }
+ *   -> { model, answers: { key: Answer }, usage: { input_tokens, output_tokens }, meta? }
+ *
+ * Chat completions do NOT work with decision models. This client is provider-agnostic:
+ * TypeSafe direct, OpenRouter `/api/alpha/decisions`, and AI/ML API all accept this schema.
+ */
+
+export type JevQuestion =
+	| { type: "noul"; instructions: string; criteria?: { true: string; false: string } }
+	| { type: "choice"; instructions: string; criteria: Record<string, string | null> }
+	| { type: "score"; instructions: string; criteria: string[] };
+
+export interface NoulAnswer {
+	type: "noul";
+	noul: number;
+}
+export interface ChoiceAnswer {
+	type: "choice";
+	choice: string;
+	confidence: number;
+	probabilities: Record<string, number>;
+}
+export interface ScoreAnswer {
+	type: "score";
+	score: number;
+	confidence: number;
+	legend: Record<string, string>;
+	probabilities: Record<string, number>;
+}
+export type JevAnswer = NoulAnswer | ChoiceAnswer | ScoreAnswer;
+
+export interface JevUsage {
+	input_tokens: number;
+	output_tokens: number;
+	cost?: number;
+}
+
+export interface JevResponse {
+	model: string;
+	provider?: string;
+	answers: Record<string, JevAnswer>;
+	usage: JevUsage;
+	meta?: unknown;
+}
+
+export interface JevClientOptions {
+	baseUrl: string;
+	apiKey: string;
+	model: string;
+	timeoutMs?: number;
+	maxRetries?: number;
+	fetchImpl?: typeof fetch;
+	userAgent?: string;
+}
+
+/**
+ * Returns the number of retry attempts left, or null when the response is final.
+ * 402 (no credits) is intentionally non-retryable: retrying cannot fix billing.
+ */
+function retryableStatus(status: number): boolean {
+	return status === 429 || status === 529 || status >= 500;
+}
+
+export class JevError extends Error {
+	readonly status: number;
+	readonly body: unknown;
+
+	constructor(message: string, status: number, body: unknown) {
+		super(message);
+		this.name = "JevError";
+		this.status = status;
+		this.body = body;
+	}
+}
+
+export function noul(instructions: string, criteria?: { true: string; false: string }): JevQuestion {
+	return criteria ? { type: "noul", instructions, criteria } : { type: "noul", instructions };
+}
+
+export function choice(instructions: string, criteria: Record<string, string | null>): JevQuestion {
+	return { type: "choice", instructions, criteria };
+}
+
+export function score(instructions: string, criteria: string[]): JevQuestion {
+	return { type: "score", instructions, criteria };
+}
+
+export function chunk<T>(items: T[], size: number): T[][] {
+	const out: T[][] = [];
+	for (let i = 0; i < items.length; i += size) out.push(items.slice(i, i + size));
+	return out;
+}
+
+export async function mapLimit<T, R>(items: T[], limit: number, fn: (item: T, index: number) => Promise<R>): Promise<R[]> {
+	const results = new Array<R>(items.length);
+	let cursor = 0;
+	const workers = Array.from({ length: Math.max(1, Math.min(limit, items.length)) }, async () => {
+		while (cursor < items.length) {
+			const index = cursor++;
+			results[index] = await fn(items[index], index);
+		}
+	});
+	await Promise.all(workers);
+	return results;
+}
+
+const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+
+export class JevClient {
+	private readonly baseUrl: string;
+	private readonly apiKey: string;
+	private readonly model: string;
+	private readonly timeoutMs: number;
+	private readonly maxRetries: number;
+	private readonly fetchImpl: typeof fetch;
+	private readonly userAgent: string;
+	readonly totals: JevUsage = { input_tokens: 0, output_tokens: 0, cost: 0 };
+
+	constructor(options: JevClientOptions) {
+		this.baseUrl = options.baseUrl;
+		this.apiKey = options.apiKey;
+		this.model = options.model;
+		this.timeoutMs = options.timeoutMs ?? 60_000;
+		this.maxRetries = options.maxRetries ?? 3;
+		this.fetchImpl = options.fetchImpl ?? fetch;
+		this.userAgent = options.userAgent ?? "jev-wiki/0.1";
+	}
+
+	async systemOne(
+		state: unknown,
+		questions: Record<string, JevQuestion>,
+		options?: { signal?: AbortSignal; model?: string; timeoutMs?: number },
+	): Promise<JevResponse> {
+		const body = JSON.stringify({ model: options?.model ?? this.model, state, questions });
+		let lastError: unknown;
+
+		for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+			const timeout = AbortSignal.timeout(options?.timeoutMs ?? this.timeoutMs);
+			const signal = options?.signal ? AbortSignal.any([options.signal, timeout]) : timeout;
+			let response: Response;
+			try {
+				response = await this.fetchImpl(this.baseUrl, {
+					method: "POST",
+					headers: {
+						"content-type": "application/json",
+						authorization: `Bearer ${this.apiKey}`,
+						"user-agent": this.userAgent,
+					},
+					body,
+					signal,
+				});
+			} catch (error) {
+				lastError = error;
+				if (attempt < this.maxRetries) {
+					await sleep(500 * 2 ** attempt);
+					continue;
+				}
+				throw new JevError(`Jev request failed: ${String((error as Error)?.message ?? error)}`, 0, undefined);
+			}
+
+			if (response.ok) {
+				const payload = (await response.json()) as JevResponse;
+				this.totals.input_tokens += payload.usage?.input_tokens ?? 0;
+				this.totals.output_tokens += payload.usage?.output_tokens ?? 0;
+				this.totals.cost = (this.totals.cost ?? 0) + (payload.usage?.cost ?? 0);
+				return payload;
+			}
+
+			const retryable = retryableStatus(response.status);
+			const text = await response.text().catch(() => "");
+			let parsed: unknown = text;
+			try {
+				parsed = JSON.parse(text);
+			} catch {
+				/* keep text */
+			}
+			lastError = new JevError(`Jev HTTP ${response.status}: ${text.slice(0, 300)}`, response.status, parsed);
+			if (!retryable || attempt === this.maxRetries) throw lastError;
+
+			const retryAfter = Number(response.headers.get("retry-after"));
+			const delay = Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter * 1000 : 500 * 2 ** attempt;
+			await sleep(delay);
+		}
+
+		throw lastError instanceof Error ? lastError : new JevError("Jev request failed", 0, undefined);
+	}
+}
+
+/** Convenience: build a client from a resolved config. */
+export function createJevClient(config: { baseUrl: string; model: string }, apiKey: string, options?: Partial<JevClientOptions>): JevClient {
+	return new JevClient({ baseUrl: config.baseUrl, model: config.model, apiKey, ...options });
+}
+
+export function isNoul(answer: JevAnswer | undefined): answer is NoulAnswer {
+	return answer?.type === "noul";
+}
+export function isChoice(answer: JevAnswer | undefined): answer is ChoiceAnswer {
+	return answer?.type === "choice";
+}
+export function isScore(answer: JevAnswer | undefined): answer is ScoreAnswer {
+	return answer?.type === "score";
+}

package/src/ledger.ts

@@ -0,0 +1,85 @@
+/**
+ * Decision ledger: every agent, Jev, and code decision with thresholds and outcomes.
+ * Newline-delimited JSON at `<wikiRoot>/.jev-wiki/decisions.jsonl`.
+ */
+import { existsSync } from "node:fs";
+import { appendFile, readFile } from "node:fs/promises";
+import { mkdir } from "node:fs/promises";
+import { dirname } from "node:path";
+import type { WikiLayout } from "./wiki/layout.ts";
+
+export type LedgerActor = "jev" | "agent" | "code";
+
+export interface LedgerEntry {
+	ts: string;
+	actor: LedgerActor;
+	op: string;
+	subject?: string;
+	verdict?: unknown;
+	thresholds?: unknown;
+	action?: string;
+	reason?: string;
+	evidence?: string[];
+	outcome?: string;
+	usage?: { input_tokens: number; output_tokens: number; cost?: number };
+	[key: string]: unknown;
+}
+
+export interface LedgerInput {
+	actor: LedgerActor;
+	op: string;
+	ts?: string;
+	subject?: string;
+	verdict?: unknown;
+	thresholds?: unknown;
+	action?: string;
+	reason?: string;
+	evidence?: string[];
+	outcome?: string;
+	usage?: { input_tokens: number; output_tokens: number; cost?: number };
+	[key: string]: unknown;
+}
+
+export async function appendLedger(layout: WikiLayout, entry: LedgerInput): Promise<void> {
+	await mkdir(dirname(layout.ledgerPath), { recursive: true });
+	const record: LedgerEntry = { ts: entry.ts ?? new Date().toISOString(), ...entry };
+	await appendFile(layout.ledgerPath, `${JSON.stringify(record)}\n`, "utf8");
+}
+
+export async function readLedger(layout: WikiLayout): Promise<LedgerEntry[]> {
+	if (!existsSync(layout.ledgerPath)) return [];
+	const text = await readFile(layout.ledgerPath, "utf8");
+	return text
+		.split(/\r?\n/)
+		.filter(Boolean)
+		.map((line) => {
+			try {
+				return JSON.parse(line) as LedgerEntry;
+			} catch {
+				return undefined;
+			}
+		})
+		.filter((entry): entry is LedgerEntry => Boolean(entry));
+}
+
+export function summarizeLedger(entries: LedgerEntry[]): {
+	total: number;
+	byActor: Record<string, number>;
+	jevTokensIn: number;
+	jevTokensOut: number;
+	jevCost: number;
+} {
+	const byActor: Record<string, number> = {};
+	let jevTokensIn = 0;
+	let jevTokensOut = 0;
+	let jevCost = 0;
+	for (const entry of entries) {
+		byActor[entry.actor] = (byActor[entry.actor] ?? 0) + 1;
+		if (entry.usage) {
+			jevTokensIn += entry.usage.input_tokens ?? 0;
+			jevTokensOut += entry.usage.output_tokens ?? 0;
+			jevCost += entry.usage.cost ?? 0;
+		}
+	}
+	return { total: entries.length, byActor, jevTokensIn, jevTokensOut, jevCost };
+}