@xynogen/pix-runtime 0.1.0

package/src/runtime.ts

@@ -0,0 +1,462 @@
+/**
+ * runtime.ts — the process singleton and PixRuntime implementation.
+ *
+ * One runtime per JavaScript process, stored under a globalThis symbol so
+ * duplicate compatible npm copies share one write queue. Reads are synchronous
+ * after a lazy load; writes are serialized and atomic.
+ */
+
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { DiagnosticSink } from "./diagnostics.ts";
+import {
+	type ConfigChange,
+	type ConfigChangeOrigin,
+	type ConfigListener,
+	type ConfigSnapshot,
+	EventBus,
+	makeSnapshot,
+	type SubscribeOptions,
+} from "./events.ts";
+import { importOptimizerSidecar, migrate } from "./migrations.ts";
+import {
+	ConfigWriteError,
+	FileStorage,
+	parseRawDocument,
+	type StorageAdapter,
+	serializeRawDocument,
+	WriteQueue,
+} from "./persistence.ts";
+import { SectionRegistry } from "./registry.ts";
+import {
+	CONFIG_FORMAT_VERSION,
+	type ConfigDiagnostic,
+	clone,
+	type DeepPartial,
+	deepMerge,
+	diffPaths,
+	isObj,
+	type ParseContext,
+	type RawDocument,
+	type SectionHandle,
+	stripDefaults,
+} from "./schema.ts";
+
+export interface InitOptions {
+	origin?: ConfigChangeOrigin;
+	source?: string;
+}
+
+export interface UpdateOptions {
+	origin?: ConfigChangeOrigin;
+	source?: string;
+}
+
+export interface ReloadOptions {
+	origin?: ConfigChangeOrigin;
+	source?: string;
+}
+
+export interface RuntimeAdapters {
+	agentDir?: string;
+	storage?: StorageAdapter;
+	registry?: SectionRegistry;
+}
+
+export interface PixRuntime {
+	readonly path: string;
+	readonly ready: boolean;
+	init(options?: InitOptions): Promise<ConfigSnapshot>;
+	flush(): Promise<void>;
+	shutdown(): Promise<void>;
+	snapshot(): ConfigSnapshot;
+	get<K extends string, T>(section: SectionHandle<K, T>): Readonly<T>;
+	update<K extends string, T>(
+		section: SectionHandle<K, T>,
+		updater: DeepPartial<T> | ((current: Readonly<T>) => T),
+		options?: UpdateOptions,
+	): Promise<ConfigChange | undefined>;
+	reset<K extends string, T>(
+		section: SectionHandle<K, T>,
+		paths?: readonly string[],
+		options?: UpdateOptions,
+	): Promise<ConfigChange | undefined>;
+	reload(options?: ReloadOptions): Promise<ConfigChange | undefined>;
+	subscribe(listener: ConfigListener, options?: SubscribeOptions): () => void;
+	diagnostics(): readonly ConfigDiagnostic[];
+}
+
+class RuntimeImpl implements PixRuntime {
+	private readonly storage: StorageAdapter;
+	private readonly registry: SectionRegistry;
+	private readonly queue = new WriteQueue();
+	private readonly bus = new EventBus();
+	private readonly sink = new DiagnosticSink();
+
+	private revision = 0;
+	private current: ConfigSnapshot | null = null;
+	private readonly agentDir: string;
+	private initPromise: Promise<ConfigSnapshot> | null = null;
+	private readOnly = false;
+
+	constructor(adapters: RuntimeAdapters = {}) {
+		this.agentDir = adapters.agentDir ?? getAgentDir();
+		this.storage = adapters.storage ?? new FileStorage(this.agentDir);
+		this.registry = adapters.registry ?? new SectionRegistry();
+	}
+
+	get path(): string {
+		return this.storage.path;
+	}
+
+	get ready(): boolean {
+		return this.current !== null;
+	}
+
+	private parseContext(): ParseContext {
+		return { diagnostic: (d) => this.sink.push(d) };
+	}
+
+	/** Resolve every section from a raw document into a values map. */
+	private resolve(doc: RawDocument): Map<string, unknown> {
+		const ctx = this.parseContext();
+		const values = new Map<string, unknown>();
+		for (const section of this.registry.all()) {
+			values.set(section.key, section.parse(doc[section.key], ctx));
+		}
+		return values;
+	}
+
+	private publish(values: Map<string, unknown>): ConfigSnapshot {
+		this.revision += 1;
+		this.current = makeSnapshot(this.revision, values);
+		return this.current;
+	}
+
+	/** Synchronous lazy load — read-only, never migrates or writes. */
+	private lazyLoad(): ConfigSnapshot {
+		if (this.current) return this.current;
+		let doc: RawDocument = {};
+		try {
+			doc = parseRawDocument(this.storage.readRaw());
+		} catch (err) {
+			this.sink.push({
+				code: "READ_FAILED",
+				severity: "warning",
+				message: "config read failed; using defaults",
+				cause: err,
+			});
+		}
+		return this.publish(this.resolve(doc));
+	}
+
+	snapshot(): ConfigSnapshot {
+		return this.current ?? this.lazyLoad();
+	}
+
+	get<K extends string, T>(section: SectionHandle<K, T>): Readonly<T> {
+		return this.snapshot().get(section);
+	}
+
+	diagnostics(): readonly ConfigDiagnostic[] {
+		return this.sink.all();
+	}
+
+	subscribe(listener: ConfigListener, options: SubscribeOptions = {}): () => void {
+		const unsub = this.bus.subscribe({ listener, paths: options.paths });
+		if (options.immediate) {
+			listener({
+				revision: this.revision,
+				origin: "init",
+				changed: [],
+				current: this.snapshot(),
+				persisted: false,
+			});
+		}
+		return unsub;
+	}
+
+	/** Single-flight initialization: migrate, import sidecars, publish. */
+	init(options: InitOptions = {}): Promise<ConfigSnapshot> {
+		if (this.initPromise) return this.initPromise;
+		this.initPromise = this.queue.run(async () => {
+			const hadLazy = this.current !== null;
+			const previous = this.current;
+			this.storage.ensureDir();
+			const doc = parseRawDocument(this.storage.readRaw());
+			const ctx = this.parseContext();
+
+			const migrated = migrate(doc, ctx);
+			this.readOnly = migrated.document.$version !== CONFIG_FORMAT_VERSION;
+
+			let working = migrated.document;
+			let needsWrite = migrated.changed;
+			let archive: (() => void) | undefined;
+
+			if (!this.readOnly) {
+				const sidecar = importOptimizerSidecar(working, this.agentDir, ctx);
+				if (sidecar.changed) needsWrite = true;
+				archive = sidecar.archive;
+			}
+
+			if (needsWrite && !this.readOnly) {
+				try {
+					this.persist(working);
+					archive?.();
+				} catch (err) {
+					this.sink.push({
+						code: "WRITE_FAILED",
+						severity: "error",
+						message: "initial migration write failed",
+						cause: err,
+					});
+				}
+			} else if (this.readOnly) {
+				working = doc; // do not normalize a future-version file
+			}
+
+			const values = this.resolve(working);
+			const snapshot = this.publish(values);
+
+			if (previous) {
+				const changed = this.changedPaths(previous, snapshot);
+				if (changed.length > 0) {
+					this.dispatch({
+						revision: this.revision,
+						origin: hadLazy ? "migration" : (options.origin ?? "init"),
+						source: options.source,
+						changed,
+						previous,
+						current: snapshot,
+						persisted: needsWrite,
+					});
+				}
+			} else {
+				this.dispatch({
+					revision: this.revision,
+					origin: options.origin ?? "init",
+					source: options.source,
+					changed: [],
+					current: snapshot,
+					persisted: needsWrite,
+				});
+			}
+			return snapshot;
+		});
+		return this.initPromise;
+	}
+
+	/** Serialize the current resolved values into a sparse raw document. */
+	private buildRawFromValues(values: Map<string, unknown>, base: RawDocument): RawDocument {
+		const doc: RawDocument = { ...base, $version: CONFIG_FORMAT_VERSION };
+		for (const section of this.registry.all()) {
+			const value = values.get(section.key);
+			const serialized = section.serialize
+				? section.serialize(value, section.defaults)
+				: this.defaultStrip(value, section.defaults);
+			if (serialized === undefined) delete doc[section.key];
+			else doc[section.key] = serialized;
+		}
+		return doc;
+	}
+
+	private defaultStrip(value: unknown, defaults: unknown): unknown {
+		if (!isObj(value) || !isObj(defaults)) {
+			return JSON.stringify(value) === JSON.stringify(defaults) ? undefined : value;
+		}
+		const copy = { ...value };
+		return stripDefaults(copy, defaults) > 0 ? copy : undefined;
+	}
+
+	private persist(doc: RawDocument): void {
+		this.storage.writeAtomic(serializeRawDocument(doc));
+	}
+
+	private changedPaths(prev: ConfigSnapshot, next: ConfigSnapshot): string[] {
+		const out: string[] = [];
+		for (const section of this.registry.all()) {
+			const handle = { key: section.key, defaults: section.defaults, __section: section };
+			out.push(...diffPaths(section.key, prev.get(handle as never), next.get(handle as never)));
+		}
+		return out;
+	}
+
+	private dispatch(change: ConfigChange): void {
+		this.bus.emit(change, (err) =>
+			this.sink.push({
+				code: "LISTENER_FAILED",
+				severity: "warning",
+				message: "config listener threw",
+				cause: err,
+			}),
+		);
+	}
+
+	update<K extends string, T>(
+		section: SectionHandle<K, T>,
+		updater: DeepPartial<T> | ((current: Readonly<T>) => T),
+		options: UpdateOptions = {},
+	): Promise<ConfigChange | undefined> {
+		return this.queue.run(async () => this.commit(section, updater, options, "api"));
+	}
+
+	reset<K extends string, T>(
+		section: SectionHandle<K, T>,
+		paths?: readonly string[],
+		options: UpdateOptions = {},
+	): Promise<ConfigChange | undefined> {
+		return this.queue.run(async () => {
+			// Full reset to defaults, or per-path restore. Always a function
+			// updater so defaults *replace* rather than deep-merge onto current.
+			const updater = (current: Readonly<T>): T => {
+				if (!paths || paths.length === 0) return clone(section.defaults) as T;
+				const next = clone(current) as Record<string, unknown>;
+				const defs = section.defaults as Record<string, unknown>;
+				for (const p of paths) {
+					const key = p.startsWith(`${section.key}.`) ? p.slice(section.key.length + 1) : p;
+					if (key in defs) next[key] = clone(defs[key]);
+				}
+				return next as T;
+			};
+			return this.commit(section, updater, options, "api");
+		});
+	}
+
+	/** Core transaction: read latest on-disk, apply update, persist, publish. */
+	private commit<K extends string, T>(
+		section: SectionHandle<K, T>,
+		updater: DeepPartial<T> | ((current: Readonly<T>) => T),
+		options: UpdateOptions,
+		defaultOrigin: ConfigChangeOrigin,
+	): ConfigChange | undefined {
+		if (this.readOnly) {
+			this.sink.push({
+				code: "UNSUPPORTED_CONFIG_VERSION",
+				severity: "error",
+				path: section.key,
+				message: "config is read-only (newer $version)",
+			});
+			return undefined;
+		}
+
+		const previous = this.snapshot();
+		const base = parseRawDocument(this.storage.readRaw());
+		const ctx = this.parseContext();
+
+		// Re-resolve all sections from the latest on-disk doc so unknown fields
+		// and sibling sections survive.
+		const values = new Map<string, unknown>();
+		for (const s of this.registry.all()) values.set(s.key, s.parse(base[s.key], ctx));
+
+		const currentValue = values.get(section.key) as Readonly<T>;
+		const nextValue =
+			typeof updater === "function"
+				? (updater as (c: Readonly<T>) => T)(currentValue)
+				: deepMerge(currentValue as T, updater);
+
+		if (JSON.stringify(currentValue) === JSON.stringify(nextValue)) return undefined;
+		values.set(section.key, nextValue);
+
+		const doc = this.buildRawFromValues(values, base);
+		try {
+			this.persist(doc);
+		} catch (err) {
+			this.sink.push({
+				code: "WRITE_FAILED",
+				severity: "error",
+				path: section.key,
+				message: "config write failed; snapshot unchanged",
+				cause: err,
+			});
+			if (err instanceof ConfigWriteError) return undefined;
+			return undefined;
+		}
+
+		const snapshot = this.publish(values);
+		const change: ConfigChange = {
+			revision: this.revision,
+			origin: options.origin ?? defaultOrigin,
+			source: options.source,
+			changed: this.changedPaths(previous, snapshot),
+			previous,
+			current: snapshot,
+			persisted: true,
+		};
+		if (change.changed.length === 0) return undefined;
+		this.dispatch(change);
+		return change;
+	}
+
+	reload(options: ReloadOptions = {}): Promise<ConfigChange | undefined> {
+		return this.queue.run(async () => {
+			const previous = this.snapshot();
+			const doc = parseRawDocument(this.storage.readRaw());
+			const values = this.resolve(doc);
+			const snapshot = this.publish(values);
+			const changed = this.changedPaths(previous, snapshot);
+			if (changed.length === 0) return undefined;
+			const change: ConfigChange = {
+				revision: this.revision,
+				origin: options.origin ?? "reload",
+				source: options.source,
+				changed,
+				previous,
+				current: snapshot,
+				persisted: false,
+			};
+			this.dispatch(change);
+			return change;
+		});
+	}
+
+	flush(): Promise<void> {
+		// All writes are synchronous inside queued tasks; draining the queue
+		// guarantees pending transactions have settled.
+		return this.queue.run(async () => undefined);
+	}
+
+	async shutdown(): Promise<void> {
+		await this.flush();
+		this.bus.clear();
+	}
+}
+
+// ── Process singleton ────────────────────────────────────────────────────────
+
+const SINGLETON_KEY = Symbol.for("@xynogen/pix-runtime");
+
+interface Global {
+	[SINGLETON_KEY]?: PixRuntime;
+}
+
+export function pixRuntime(): PixRuntime {
+	const g = globalThis as Global;
+	if (!g[SINGLETON_KEY]) g[SINGLETON_KEY] = new RuntimeImpl();
+	return g[SINGLETON_KEY];
+}
+
+/** Test/entry hook: create an isolated runtime with injected adapters. */
+export function createRuntime(adapters: RuntimeAdapters = {}): PixRuntime {
+	return new RuntimeImpl(adapters);
+}
+
+// ── Convenience delegates ────────────────────────────────────────────────────
+
+export function config<K extends string, T>(section: SectionHandle<K, T>): Readonly<T> {
+	return pixRuntime().get(section);
+}
+
+export function updateConfig<K extends string, T>(
+	section: SectionHandle<K, T>,
+	patch: DeepPartial<T> | ((current: Readonly<T>) => T),
+	options?: UpdateOptions,
+): Promise<ConfigChange | undefined> {
+	return pixRuntime().update(section, patch, options);
+}
+
+export function onConfigChange(listener: ConfigListener, options?: SubscribeOptions): () => void {
+	return pixRuntime().subscribe(listener, options);
+}
+
+export function reloadConfig(options?: ReloadOptions): Promise<ConfigChange | undefined> {
+	return pixRuntime().reload(options);
+}

package/src/schema.ts

@@ -0,0 +1,191 @@
+/**
+ * schema.ts — shared types, validation helpers, and immutability utilities for
+ * the pix-runtime config layer.
+ *
+ * The runtime models config as typed *sections*. A section owns its defaults,
+ * a pure `parse(raw)`, and an optional `serialize(value, defaults)`. Parsing
+ * never throws: invalid fields fall back individually and push a diagnostic.
+ */
+
+export const CONFIG_FORMAT_VERSION = 1 as const;
+
+// ── Raw document ─────────────────────────────────────────────────────────────
+
+/** The on-disk JSON shape: sparse, `$version` plus known/unknown sections. */
+export type RawDocument = Record<string, unknown>;
+
+// ── Diagnostics ──────────────────────────────────────────────────────────────
+
+export type ConfigDiagnosticCode =
+	| "PARSE_ERROR"
+	| "INVALID_VALUE"
+	| "READ_FAILED"
+	| "WRITE_FAILED"
+	| "MIGRATION_FAILED"
+	| "UNSUPPORTED_CONFIG_VERSION"
+	| "LISTENER_FAILED";
+
+export interface ConfigDiagnostic {
+	code: ConfigDiagnosticCode;
+	severity: "warning" | "error";
+	path?: string;
+	message: string;
+	cause?: unknown;
+	at: number;
+}
+
+/** Collects diagnostics while parsing/migrating without throwing. */
+export interface ParseContext {
+	diagnostic(d: Omit<ConfigDiagnostic, "at">): void;
+}
+
+// ── Section definitions ──────────────────────────────────────────────────────
+
+export interface ConfigSection<T> {
+	key: string;
+	defaults: Readonly<T>;
+	parse(raw: unknown, ctx: ParseContext): T;
+	/**
+	 * Serialize a resolved value into a sparse raw object relative to defaults.
+	 * When omitted, the runtime deep-strips values equal to defaults.
+	 */
+	serialize?(value: T, defaults: T): unknown;
+}
+
+/** Opaque, typed handle to a registered section. */
+export interface SectionHandle<K extends string, T> {
+	readonly key: K;
+	readonly defaults: Readonly<T>;
+	/** Internal reference to the full definition. */
+	readonly __section: ConfigSection<T>;
+}
+
+export function defineSection<const K extends string, T>(
+	definition: ConfigSection<T> & { key: K },
+): SectionHandle<K, T> {
+	return {
+		key: definition.key,
+		defaults: definition.defaults,
+		__section: definition,
+	};
+}
+
+// ── Value coercion helpers (pure, never throw) ───────────────────────────────
+
+export function isObj(v: unknown): v is Record<string, unknown> {
+	return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+
+export function boolOr(v: unknown, fallback: boolean): boolean {
+	return typeof v === "boolean" ? v : fallback;
+}
+
+export function posNumOr(v: unknown, fallback: number): number {
+	return typeof v === "number" && Number.isFinite(v) && v > 0 ? v : fallback;
+}
+
+export function enumOr<T extends string>(v: unknown, allowed: readonly T[], fallback: T): T {
+	return typeof v === "string" && (allowed as readonly string[]).includes(v) ? (v as T) : fallback;
+}
+
+export function strArr(v: unknown): string[] {
+	if (!Array.isArray(v)) return [];
+	return v.filter((x): x is string => typeof x === "string");
+}
+
+// ── Sparse serialization ─────────────────────────────────────────────────────
+
+/**
+ * Recursively remove entries equal to their default. Returns the number of
+ * remaining keys so callers can drop empty sections. Mutates `section`.
+ */
+export function stripDefaults(
+	section: Record<string, unknown>,
+	defaults: Record<string, unknown>,
+): number {
+	for (const [key, defaultValue] of Object.entries(defaults)) {
+		const value = section[key];
+		if (isObj(value) && isObj(defaultValue)) {
+			const nested = { ...value };
+			if (stripDefaults(nested, defaultValue) > 0) section[key] = nested;
+			else delete section[key];
+		} else if (JSON.stringify(value) === JSON.stringify(defaultValue)) {
+			delete section[key];
+		}
+	}
+	return Object.keys(section).length;
+}
+
+// ── Immutability ─────────────────────────────────────────────────────────────
+
+/** Deep-freeze a value in place and return it typed as readonly. */
+export function deepFreeze<T>(value: T): T {
+	if (value && typeof value === "object" && !Object.isFrozen(value)) {
+		Object.freeze(value);
+		for (const key of Object.keys(value as Record<string, unknown>)) {
+			deepFreeze((value as Record<string, unknown>)[key]);
+		}
+	}
+	return value;
+}
+
+/** Deep clone a JSON-compatible value via the native structured clone. */
+export function clone<T>(value: T): T {
+	return structuredClone(value);
+}
+
+// ── Deep merge (objects merge, arrays/primitives replace) ────────────────────
+
+export type DeepPartial<T> = T extends (infer U)[]
+	? U[]
+	: T extends object
+		? { [K in keyof T]?: DeepPartial<T[K]> }
+		: T;
+
+/**
+ * Merge `patch` onto `base`. Objects merge recursively; arrays replace;
+ * `undefined` values are rejected (skipped). Returns a new object.
+ */
+export function deepMerge<T>(base: T, patch: DeepPartial<T>): T {
+	if (!isObj(base) || !isObj(patch)) return (patch as unknown as T) ?? base;
+	const out: Record<string, unknown> = { ...(base as Record<string, unknown>) };
+	for (const [key, value] of Object.entries(patch as Record<string, unknown>)) {
+		if (value === undefined) continue;
+		const prev = out[key];
+		if (isObj(prev) && isObj(value)) {
+			out[key] = deepMerge<Record<string, unknown>>(
+				prev,
+				value as DeepPartial<Record<string, unknown>>,
+			);
+		} else {
+			out[key] = value;
+		}
+	}
+	return out as T;
+}
+
+// ── Changed-path detection ───────────────────────────────────────────────────
+
+/** Return dotted JSON paths that differ between two resolved section values. */
+export function diffPaths(prefix: string, a: unknown, b: unknown): string[] {
+	if (JSON.stringify(a) === JSON.stringify(b)) return [];
+	if (!isObj(a) || !isObj(b)) return [prefix];
+	const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+	const out: string[] = [];
+	for (const key of keys) {
+		out.push(...diffPaths(prefix ? `${prefix}.${key}` : key, a[key], b[key]));
+	}
+	return out;
+}
+
+/** Match a changed path against subscription filters (supports `section.*`). */
+export function pathMatches(changed: string, filters: readonly string[]): boolean {
+	return filters.some((f) => {
+		if (f === changed) return true;
+		if (f.endsWith(".*")) {
+			const base = f.slice(0, -2);
+			return changed === base || changed.startsWith(`${base}.`);
+		}
+		return false;
+	});
+}

package/src/sections/collapse.ts

@@ -0,0 +1,35 @@
+import { boolOr, defineSection, isObj, posNumOr } from "../schema.ts";
+
+export interface CollapseConfig {
+	/** Master toggle. `false` = never collapse any tool. Default `true`. */
+	enabled: boolean;
+	/** Seconds before a tool card collapses. Default `10`. */
+	delaySec: number;
+	/** Per-tool overrides. Missing key follows `enabled`. */
+	tools: Partial<Record<string, boolean>>;
+}
+
+const DEFAULTS: Readonly<CollapseConfig> = {
+	enabled: true,
+	delaySec: 10,
+	tools: {},
+};
+
+export const collapseSection = defineSection<"collapse", CollapseConfig>({
+	key: "collapse",
+	defaults: DEFAULTS,
+	parse(raw) {
+		if (!isObj(raw)) return { ...DEFAULTS, tools: {} };
+		const tools: Partial<Record<string, boolean>> = {};
+		if (isObj(raw.tools)) {
+			for (const [k, v] of Object.entries(raw.tools)) {
+				if (typeof v === "boolean") tools[k] = v;
+			}
+		}
+		return {
+			enabled: boolOr(raw.enabled, DEFAULTS.enabled),
+			delaySec: posNumOr(raw.delaySec, DEFAULTS.delaySec),
+			tools,
+		};
+	},
+});