@iowarp/clio-coder 0.3.0 → 0.3.1

package/src/domains/memory/validate.ts

@@ -0,0 +1,297 @@
+import { isAbsolute, resolve } from "node:path";
+import {
+	MEMORY_SCOPES,
+	MEMORY_VERSION,
+	type MemoryRecord,
+	type MemoryRecordValidationResult,
+	type MemoryRepositoryIdentity,
+	type MemoryScope,
+	type MemoryStoreValidationResult,
+	type MemoryValidationIssue,
+} from "./types.js";
+
+const ID_PATTERN = /^mem-[a-f0-9]{16}$/;
+
+function isMemoryScope(value: string): value is MemoryScope {
+	return (MEMORY_SCOPES as ReadonlyArray<string>).includes(value);
+}
+
+export function validateMemoryRecord(value: unknown, source = "$"): MemoryRecordValidationResult {
+	const issues: MemoryValidationIssue[] = [];
+	const record = readMemoryRecord(value, source, issues);
+	if (record === null || issues.length > 0) return { valid: false, issues };
+	return { valid: true, record };
+}
+
+export function validateMemoryStore(value: unknown, source = "$"): MemoryStoreValidationResult {
+	const issues: MemoryValidationIssue[] = [];
+	if (!isRecord(value)) return { valid: false, issues: [{ path: source, message: "expected object" }] };
+	rejectUnexpectedFields(value, source, ["version", "records"], issues);
+	if (value.version !== MEMORY_VERSION) issues.push({ path: `${source}.version`, message: "expected 1" });
+	const rawRecords = value.records;
+	if (!Array.isArray(rawRecords)) {
+		issues.push({ path: `${source}.records`, message: "expected array" });
+		return { valid: false, issues };
+	}
+	const records: MemoryRecord[] = [];
+	for (let index = 0; index < rawRecords.length; index += 1) {
+		const record = readMemoryRecord(rawRecords[index], `${source}.records[${index}]`, issues);
+		if (record !== null) records.push(record);
+	}
+	if (issues.length > 0) return { valid: false, issues };
+	return { valid: true, store: { version: MEMORY_VERSION, records } };
+}
+
+function readMemoryRecord(value: unknown, path: string, issues: MemoryValidationIssue[]): MemoryRecord | null {
+	if (!isRecord(value)) {
+		issues.push({ path, message: "expected object" });
+		return null;
+	}
+	rejectUnexpectedFields(
+		value,
+		path,
+		[
+			"id",
+			"scope",
+			"key",
+			"lesson",
+			"evidenceRefs",
+			"appliesWhen",
+			"avoidWhen",
+			"confidence",
+			"createdAt",
+			"lastVerifiedAt",
+			"regressions",
+			"approved",
+			"rejectedAt",
+			"repository",
+		],
+		issues,
+	);
+	const id = readString(value, `${path}.id`, issues);
+	if (id !== null && !ID_PATTERN.test(id)) {
+		issues.push({ path: `${path}.id`, message: "expected mem- followed by 16 lowercase hex characters" });
+	}
+	const scopeValue = readString(value, `${path}.scope`, issues);
+	const scope = scopeValue !== null && isMemoryScope(scopeValue) ? scopeValue : null;
+	if (scopeValue !== null && scope === null) issues.push({ path: `${path}.scope`, message: "expected memory scope" });
+	const key = readString(value, `${path}.key`, issues);
+	const lesson = readString(value, `${path}.lesson`, issues);
+	const evidenceRefs = readStringArray(value, `${path}.evidenceRefs`, issues);
+	if (evidenceRefs !== null && evidenceRefs.length === 0) {
+		issues.push({ path: `${path}.evidenceRefs`, message: "expected at least one evidence ref" });
+	}
+	const appliesWhen = readStringArray(value, `${path}.appliesWhen`, issues);
+	const avoidWhen = readStringArray(value, `${path}.avoidWhen`, issues);
+	const confidence = readNumber(value, `${path}.confidence`, issues);
+	if (confidence !== null && (confidence < 0 || confidence > 1)) {
+		issues.push({ path: `${path}.confidence`, message: "expected number between 0 and 1" });
+	}
+	const createdAt = readIsoString(value, `${path}.createdAt`, issues);
+	const lastVerifiedAt = readOptionalIsoString(value, `${path}.lastVerifiedAt`, issues);
+	const regressions = readOptionalStringArray(value, `${path}.regressions`, issues);
+	const approved = readBoolean(value, `${path}.approved`, issues);
+	const rejectedAt = readOptionalIsoString(value, `${path}.rejectedAt`, issues);
+	const repository = readOptionalMemoryRepositoryIdentity(value, `${path}.repository`, issues);
+	if (approved === true && rejectedAt !== undefined) {
+		issues.push({ path: `${path}.rejectedAt`, message: "approved records must not be rejected" });
+	}
+	if (repository !== undefined && scope !== null && scope !== "repo") {
+		issues.push({ path: `${path}.repository`, message: "repository applicability requires repo scope" });
+	}
+	if (repository === undefined && scope === "repo") {
+		issues.push({ path: `${path}.repository`, message: "repo scope requires repository applicability" });
+	}
+	if (
+		id === null ||
+		scope === null ||
+		key === null ||
+		lesson === null ||
+		evidenceRefs === null ||
+		appliesWhen === null ||
+		avoidWhen === null ||
+		confidence === null ||
+		createdAt === null ||
+		approved === null
+	) {
+		return null;
+	}
+	const record: MemoryRecord = {
+		id,
+		scope,
+		key,
+		lesson,
+		evidenceRefs,
+		appliesWhen,
+		avoidWhen,
+		confidence,
+		createdAt,
+		approved,
+	};
+	if (lastVerifiedAt !== undefined) record.lastVerifiedAt = lastVerifiedAt;
+	if (regressions !== undefined) record.regressions = regressions;
+	if (rejectedAt !== undefined) record.rejectedAt = rejectedAt;
+	if (repository !== undefined) record.repository = repository;
+	return record;
+}
+
+function readOptionalMemoryRepositoryIdentity(
+	record: Record<string, unknown>,
+	path: string,
+	issues: MemoryValidationIssue[],
+): MemoryRepositoryIdentity | undefined {
+	const field = fieldName(path);
+	if (!Object.hasOwn(record, field)) return undefined;
+	const value = record[field];
+	if (!isRecord(value)) {
+		issues.push({ path, message: "expected object" });
+		return undefined;
+	}
+	rejectUnexpectedFields(value, path, ["kind", "key"], issues);
+	const kind = readString(value, `${path}.kind`, issues);
+	if (kind !== null && kind !== "canonical-path") {
+		issues.push({ path: `${path}.kind`, message: "expected canonical-path" });
+	}
+	const key = readString(value, `${path}.key`, issues);
+	if (key !== null && !isNormalizedAbsoluteRepositoryPath(key)) {
+		issues.push({ path: `${path}.key`, message: "expected normalized absolute repository path" });
+	}
+	if (kind !== "canonical-path" || key === null || !isNormalizedAbsoluteRepositoryPath(key)) return undefined;
+	return { kind, key };
+}
+
+function isNormalizedAbsoluteRepositoryPath(value: string): boolean {
+	return !/[\0\r\n]/u.test(value) && isAbsolute(value) && resolve(value) === value;
+}
+
+function rejectUnexpectedFields(
+	record: Record<string, unknown>,
+	path: string,
+	allowed: ReadonlyArray<string>,
+	issues: MemoryValidationIssue[],
+): void {
+	const allowedSet = new Set(allowed);
+	for (const key of Object.keys(record).sort(compareStrings)) {
+		if (!allowedSet.has(key)) issues.push({ path: `${path}.${key}`, message: "unknown field" });
+	}
+}
+
+function readString(record: Record<string, unknown>, path: string, issues: MemoryValidationIssue[]): string | null {
+	const value = readField(record, path, issues);
+	if (typeof value !== "string" || value.length === 0) {
+		issues.push({ path, message: "expected non-empty string" });
+		return null;
+	}
+	return value;
+}
+
+function readIsoString(record: Record<string, unknown>, path: string, issues: MemoryValidationIssue[]): string | null {
+	const value = readString(record, path, issues);
+	if (value === null) return null;
+	if (!isValidIsoTimestamp(value)) issues.push({ path, message: "expected ISO timestamp" });
+	return value;
+}
+
+function readOptionalIsoString(
+	record: Record<string, unknown>,
+	path: string,
+	issues: MemoryValidationIssue[],
+): string | undefined {
+	const key = fieldName(path);
+	if (!Object.hasOwn(record, key)) return undefined;
+	const value = record[key];
+	if (typeof value !== "string" || value.length === 0) {
+		issues.push({ path, message: "expected non-empty string" });
+		return undefined;
+	}
+	if (!isValidIsoTimestamp(value)) issues.push({ path, message: "expected ISO timestamp" });
+	return value;
+}
+
+function readStringArray(
+	record: Record<string, unknown>,
+	path: string,
+	issues: MemoryValidationIssue[],
+): string[] | null {
+	const value = readField(record, path, issues);
+	if (!Array.isArray(value)) {
+		issues.push({ path, message: "expected string array" });
+		return null;
+	}
+	const out: string[] = [];
+	for (let index = 0; index < value.length; index += 1) {
+		const item = value[index];
+		if (typeof item !== "string" || item.length === 0) {
+			issues.push({ path: `${path}[${index}]`, message: "expected non-empty string" });
+			continue;
+		}
+		out.push(item);
+	}
+	return out;
+}
+
+function readOptionalStringArray(
+	record: Record<string, unknown>,
+	path: string,
+	issues: MemoryValidationIssue[],
+): string[] | undefined {
+	const key = fieldName(path);
+	if (!Object.hasOwn(record, key)) return undefined;
+	const value = record[key];
+	if (!Array.isArray(value)) {
+		issues.push({ path, message: "expected string array" });
+		return undefined;
+	}
+	const out: string[] = [];
+	for (let index = 0; index < value.length; index += 1) {
+		const item = value[index];
+		if (typeof item !== "string" || item.length === 0) {
+			issues.push({ path: `${path}[${index}]`, message: "expected non-empty string" });
+			continue;
+		}
+		out.push(item);
+	}
+	return out;
+}
+
+function readNumber(record: Record<string, unknown>, path: string, issues: MemoryValidationIssue[]): number | null {
+	const value = readField(record, path, issues);
+	if (typeof value !== "number" || !Number.isFinite(value)) {
+		issues.push({ path, message: "expected number" });
+		return null;
+	}
+	return value;
+}
+
+function readBoolean(record: Record<string, unknown>, path: string, issues: MemoryValidationIssue[]): boolean | null {
+	const value = readField(record, path, issues);
+	if (typeof value !== "boolean") {
+		issues.push({ path, message: "expected boolean" });
+		return null;
+	}
+	return value;
+}
+
+function readField(record: Record<string, unknown>, path: string, issues: MemoryValidationIssue[]): unknown {
+	const key = fieldName(path);
+	if (!Object.hasOwn(record, key)) issues.push({ path, message: "missing required field" });
+	return record[key];
+}
+
+function fieldName(path: string): string {
+	const parts = path.split(".");
+	return parts[parts.length - 1] ?? path;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isValidIsoTimestamp(value: string): boolean {
+	const timestamp = Date.parse(value);
+	return Number.isFinite(timestamp) && new Date(timestamp).toISOString() === value;
+}
+
+function compareStrings(a: string, b: string): number {
+	return a.localeCompare(b);
+}

package/src/domains/middleware/budget.ts

@@ -0,0 +1,216 @@
+/**
+ * Phase-aware soft budgets for middleware hook evaluation, plus the rolling
+ * warmup/steady-state tracker that decides when an overrun is worth surfacing.
+ *
+ * The flat 10ms-per-call budget was wrong on two counts: it fired on one-time
+ * JIT/module warmup (the first turn_end reading the session ledger), and it
+ * treated every hook phase the same. `before_tool`/`after_tool` sit on the tool
+ * hot path and must stay tight; `turn_start`/`turn_end`/`on_compaction` run once
+ * per turn off the token stream and may do bounded I/O, so they are forgiving.
+ *
+ * The tracker is pure over its inputs: elapsed time is passed in (never read
+ * from a clock here) and all state lives in the tracker instance, so tests drive
+ * warmup and rolling-window behaviour deterministically by constructing a
+ * tracker and calling `record` with fixed elapsed values.
+ */
+
+import { MIDDLEWARE_HOOKS, type MiddlewareHook } from "./types.js";
+
+/**
+ * Forgiving, phase-aware defaults (ms). Tuned against the measured cost of the
+ * once-per-turn assessors: the finish-contract's first turn_end warms the
+ * session reader (~23ms observed), well under the 75ms turn_end budget, so it is
+ * no longer flagged, while the hot-path hooks keep a tight 25ms.
+ */
+export const DEFAULT_MIDDLEWARE_HOOK_BUDGETS_MS: Readonly<Record<MiddlewareHook, number>> = {
+	before_tool: 25,
+	after_tool: 25,
+	turn_start: 50,
+	turn_end: 75,
+	on_compaction: 150,
+};
+
+/** First N invocations per (registrationId, hook) never warn: one-time warmup. */
+export const DEFAULT_HOOK_BUDGET_WARMUP_CALLS = 1;
+/** Rolling window size M of post-warmup calls examined for steady-state slowness. */
+export const DEFAULT_HOOK_BUDGET_WINDOW = 5;
+/** Warn only when ≥N of the last M post-warmup calls exceeded budget. */
+export const DEFAULT_HOOK_BUDGET_THRESHOLD = 3;
+
+export type HookBudgetMap = Record<MiddlewareHook, number>;
+
+/** Rolling-window statistics attached to a budget outcome for observability. */
+export interface HookBudgetStats {
+	/** Total post-warmup calls seen for the key. */
+	sampleCount: number;
+	/** Samples currently held in the rolling window (≤ window size). */
+	window: number;
+	/** How many of the windowed samples exceeded budget. */
+	overCount: number;
+	p50Ms: number;
+	p95Ms: number;
+}
+
+export interface HookBudgetOutcome {
+	budgetMs: number;
+	/** This call's elapsed exceeded the phase budget. */
+	exceeded: boolean;
+	/** This call fell within the warmup grace and is never a warning. */
+	warmup: boolean;
+	/**
+	 * Steady-state signal: post-warmup, this call is over budget, AND at least
+	 * `threshold` of the last `window` post-warmup calls were over budget. A lone
+	 * spike never sets this; consistent slowness does.
+	 */
+	warn: boolean;
+	stats: HookBudgetStats;
+}
+
+export interface HookBudgetTracker {
+	budgetFor(hook: MiddlewareHook): number;
+	record(registrationId: string, hook: MiddlewareHook, elapsedMs: number): HookBudgetOutcome;
+}
+
+export interface HookBudgetTrackerOptions {
+	/** Per-phase budget overrides merged onto the defaults. */
+	budgets?: Partial<HookBudgetMap>;
+	/** Invocations per key that never warn (default 1). 0 disables the grace. */
+	warmupCalls?: number;
+	/** Rolling window size M (default 5). */
+	windowSize?: number;
+	/** Over-budget count N within the window that triggers a warning (default 3). */
+	threshold?: number;
+}
+
+function parsePositiveMs(raw: string | undefined): number | null {
+	if (raw === undefined) return null;
+	const value = Number(raw);
+	return Number.isFinite(value) && value > 0 ? value : null;
+}
+
+function parsePositiveInt(raw: string | undefined): number | null {
+	if (raw === undefined) return null;
+	const value = Number(raw);
+	return Number.isInteger(value) && value > 0 ? value : null;
+}
+
+function parseNonNegativeInt(raw: string | undefined): number | null {
+	if (raw === undefined) return null;
+	const value = Number(raw);
+	return Number.isInteger(value) && value >= 0 ? value : null;
+}
+
+/** Uppercase env suffix for a hook, e.g. `turn_end` -> `TURN_END`. */
+function hookEnvSuffix(hook: MiddlewareHook): string {
+	return hook.toUpperCase();
+}
+
+/**
+ * Resolve per-phase budgets from the environment. Precedence per phase:
+ * `CLIO_CODER_HOOK_BUDGET_<PHASE>_MS` > `CLIO_CODER_HOOK_BUDGET_MS` (global) > built-in
+ * default. Invalid or non-positive values are ignored so a typo never zeroes a
+ * budget. Lets an operator on a slow disk loosen budgets without a rebuild.
+ */
+export function resolveHookBudgetsFromEnv(env: NodeJS.ProcessEnv = process.env): HookBudgetMap {
+	const global = parsePositiveMs(env.CLIO_CODER_HOOK_BUDGET_MS);
+	const map = {} as HookBudgetMap;
+	for (const hook of MIDDLEWARE_HOOKS) {
+		const perPhase = parsePositiveMs(env[`CLIO_CODER_HOOK_BUDGET_${hookEnvSuffix(hook)}_MS`]);
+		map[hook] = perPhase ?? global ?? DEFAULT_MIDDLEWARE_HOOK_BUDGETS_MS[hook];
+	}
+	return map;
+}
+
+/** Resolve warmup/window/threshold tunables from the environment. */
+export function resolveHookBudgetTunablesFromEnv(env: NodeJS.ProcessEnv = process.env): {
+	warmupCalls: number;
+	windowSize: number;
+	threshold: number;
+} {
+	return {
+		warmupCalls: parseNonNegativeInt(env.CLIO_CODER_HOOK_BUDGET_WARMUP_CALLS) ?? DEFAULT_HOOK_BUDGET_WARMUP_CALLS,
+		windowSize: parsePositiveInt(env.CLIO_CODER_HOOK_BUDGET_WINDOW) ?? DEFAULT_HOOK_BUDGET_WINDOW,
+		threshold: parsePositiveInt(env.CLIO_CODER_HOOK_BUDGET_THRESHOLD) ?? DEFAULT_HOOK_BUDGET_THRESHOLD,
+	};
+}
+
+/** Nearest-rank percentile over a small sample; 0 for an empty window. */
+function percentile(sortedAscending: ReadonlyArray<number>, p: number): number {
+	if (sortedAscending.length === 0) return 0;
+	const rank = Math.ceil((p / 100) * sortedAscending.length);
+	const index = Math.min(sortedAscending.length - 1, Math.max(0, rank - 1));
+	return sortedAscending[index] ?? 0;
+}
+
+interface KeyState {
+	calls: number;
+	postWarmupCalls: number;
+	window: number[];
+}
+
+/**
+ * Build a session-scoped tracker. One instance persists across the whole run so
+ * warmup and the rolling window accumulate; a fresh instance (as tests and the
+ * per-call fallback create) starts every key in warmup, so the first call never
+ * warns.
+ */
+export function createHookBudgetTracker(options: HookBudgetTrackerOptions = {}): HookBudgetTracker {
+	const budgets: HookBudgetMap = { ...DEFAULT_MIDDLEWARE_HOOK_BUDGETS_MS, ...(options.budgets ?? {}) };
+	const warmupCalls = Math.max(0, options.warmupCalls ?? DEFAULT_HOOK_BUDGET_WARMUP_CALLS);
+	const windowSize = Math.max(1, options.windowSize ?? DEFAULT_HOOK_BUDGET_WINDOW);
+	// Bound the threshold by the window: overCount can never exceed the number of
+	// samples the window holds, so a threshold above windowSize would silently
+	// disable steady-state warnings forever (e.g. CLIO_CODER_HOOK_BUDGET_WINDOW=2 with
+	// the default threshold of 3). Clamp so the signal is always reachable.
+	const threshold = Math.min(windowSize, Math.max(1, options.threshold ?? DEFAULT_HOOK_BUDGET_THRESHOLD));
+	const states = new Map<string, KeyState>();
+
+	function statsFor(state: KeyState, budgetMs: number): HookBudgetStats {
+		const sorted = [...state.window].sort((a, b) => a - b);
+		const overCount = state.window.reduce((count, ms) => (ms > budgetMs ? count + 1 : count), 0);
+		return {
+			sampleCount: state.postWarmupCalls,
+			window: state.window.length,
+			overCount,
+			p50Ms: percentile(sorted, 50),
+			p95Ms: percentile(sorted, 95),
+		};
+	}
+
+	return {
+		budgetFor(hook: MiddlewareHook): number {
+			return budgets[hook];
+		},
+		record(registrationId: string, hook: MiddlewareHook, elapsedMs: number): HookBudgetOutcome {
+			const budgetMs = budgets[hook];
+			const exceeded = elapsedMs > budgetMs;
+			const key = `${registrationId}\u0000${hook}`;
+			let state = states.get(key);
+			if (state === undefined) {
+				state = { calls: 0, postWarmupCalls: 0, window: [] };
+				states.set(key, state);
+			}
+			state.calls += 1;
+			if (state.calls <= warmupCalls) {
+				return {
+					budgetMs,
+					exceeded,
+					warmup: true,
+					warn: false,
+					stats: { sampleCount: 0, window: 0, overCount: 0, p50Ms: 0, p95Ms: 0 },
+				};
+			}
+			state.postWarmupCalls += 1;
+			state.window.push(elapsedMs);
+			if (state.window.length > windowSize) state.window.shift();
+			const stats = statsFor(state, budgetMs);
+			return {
+				budgetMs,
+				exceeded,
+				warmup: false,
+				warn: exceeded && stats.overCount >= threshold,
+				stats,
+			};
+		},
+	};
+}

package/src/domains/middleware/contract.ts

@@ -0,0 +1,35 @@
+import type { MiddlewareDiagnosticSink, MiddlewareHookRegistration } from "./runtime.js";
+import type {
+	MiddlewareEffect,
+	MiddlewareHookInput,
+	MiddlewareHookResult,
+	MiddlewareRule,
+	MiddlewareSnapshot,
+} from "./types.js";
+
+export interface MiddlewareContract {
+	runHook(input: MiddlewareHookInput): MiddlewareHookResult;
+	/** Await the optional serialized phase after `runHook`; never used by tool admission. */
+	runAsyncHook?(
+		input: MiddlewareHookInput,
+		priorEffects?: ReadonlyArray<MiddlewareEffect>,
+	): Promise<MiddlewareHookResult>;
+	listRules(): ReadonlyArray<MiddlewareRule>;
+	snapshot(): MiddlewareSnapshot;
+	/**
+	 * Append a coded hook registration after every existing rule and
+	 * registration. The composition root calls this for guards that need
+	 * runtime dependencies (bus, clocks) the domain loader cannot supply at
+	 * bundle construction. Ids share one namespace with rule ids; a colliding
+	 * registration is dropped, first entry wins, matching bundle semantics.
+	 */
+	registerHook(registration: MiddlewareHookRegistration): void;
+	/**
+	 * Replace the diagnostic sink for hook isolation/budget reports. Exists
+	 * for the same reason as registerHook: the domain loader constructs the
+	 * bundle before the composition root can supply the bus-emitting sink
+	 * (Q1, `middleware.hookFailed`). Until called, diagnostics go to the
+	 * stderr writer default.
+	 */
+	setDiagnosticSink(sink: MiddlewareDiagnosticSink): void;
+}