@llblab/pi-kit 0.5.2 → 0.7.0

package/node_modules/@llblab/pi-state-flow/lib/history.ts

@@ -0,0 +1,95 @@
+import { randomUUID } from "node:crypto";
+import { isJsonValue, isObject, sameJson, validatePatch, type JsonObject } from "./json.ts";
+import type { ScopePatch, ScopedStates, StateScope } from "./state.ts";
+
+export const RECENT_TRANSITION_LIMIT = 7;
+
+export interface RecentScopePatch {
+	scope: StateScope;
+	patch: ScopePatch & { response?: string };
+}
+
+/** Exact accepted replay cohort; temporal runtime owns its causal boundary. */
+export interface AcceptedTransition {
+	id: string;
+	transitions: RecentScopePatch[];
+}
+
+/** Compact lineage projection; at is a branch-local position, not a clock. */
+export interface RecentTransition extends AcceptedTransition {
+	at: number;
+}
+
+export type RecentTransitionWindow = RecentTransition[];
+const SCOPES = new Set<StateScope>(["global", "cwd", "session"]);
+const PATCH_KEYS = new Set(["artifacts", "contract", "working", "response"]);
+
+/** Normalize accepted replacements into recursive-merge replay, including removals. */
+function replayPatch(before: JsonObject, after: JsonObject): JsonObject {
+	const entries: Array<[string, JsonObject[string]]> = [];
+	for (const key of new Set([...Object.keys(before), ...Object.keys(after)])) {
+		if (!Object.hasOwn(after, key)) {
+			entries.push([key, null]);
+			continue;
+		}
+		if (Object.hasOwn(before, key) && sameJson(before[key], after[key])) continue;
+		const previous = before[key];
+		const next = after[key]!;
+		entries.push([key, isObject(previous) && isObject(next) ? replayPatch(previous, next) : structuredClone(next)]);
+	}
+	return Object.fromEntries(entries);
+}
+
+function validateScopedPatch(value: unknown): asserts value is RecentScopePatch {
+	if (!isObject(value) || Object.keys(value).sort().join(",") !== "patch,scope") {
+		throw new Error('Recent State Flow transition entries must contain exactly "scope" and "patch"');
+	}
+	if (typeof value.scope !== "string" || !SCOPES.has(value.scope as StateScope)) {
+		throw new Error(`Recent State Flow transition has an unknown scope: ${String(value.scope)}`);
+	}
+	validatePatch(value.patch);
+	for (const [key, field] of Object.entries(value.patch)) {
+		if (!PATCH_KEYS.has(key) || (key === "response"
+			? value.scope !== "session" || typeof field !== "string" : !isObject(field))) {
+			throw new Error("Recent State Flow patches may contain object-valued artifacts, contract, and working plus a session response string");
+		}
+	}
+}
+
+export function validateRecentTransition(value: unknown): asserts value is RecentTransition {
+	if (!isObject(value) || Object.keys(value).sort().join(",") !== "at,id,transitions") throw new Error("Recent State Flow transition has an invalid envelope");
+	if (typeof value.id !== "string" || value.id.length === 0) throw new Error("Recent State Flow transition must have a non-empty id");
+	if (!Number.isSafeInteger(value.at) || (value.at as number) < 0) throw new Error("Recent State Flow transition must have a safe non-negative position");
+	if (!Array.isArray(value.transitions) || value.transitions.length === 0 || !isJsonValue(value.transitions)) throw new Error("Recent State Flow transition must contain semantic patches");
+	const seen = new Set<StateScope>();
+	for (const transition of value.transitions) {
+		validateScopedPatch(transition);
+		if (seen.has(transition.scope)) throw new Error(`Duplicate recent State Flow transition scope: ${transition.scope}`);
+		seen.add(transition.scope);
+	}
+}
+
+export function createAcceptedTransition(currentStates: ScopedStates, nextStates: ScopedStates, id?: string): AcceptedTransition | undefined {
+	const transitions: RecentScopePatch[] = [];
+	for (const scope of SCOPES) {
+		const patch = replayPatch(currentStates[scope], nextStates[scope]);
+		if (Object.keys(patch).length > 0) transitions.push({ scope, patch });
+	}
+	if (transitions.length === 0) return undefined;
+	return { id: id ?? randomUUID(), transitions };
+}
+
+/** Preserve the configured per-scope budget, filtering in selected-lineage order. */
+export function projectRecentTransitionsWithLimit(limit: number, lineage: readonly RecentTransition[]): RecentTransitionWindow {
+	if (!Number.isSafeInteger(limit) || limit < 0 || limit > RECENT_TRANSITION_LIMIT) {
+		throw new Error(`Recent State Flow transition limit must be an integer from 0 to ${RECENT_TRANSITION_LIMIT}`);
+	}
+	const remaining = { global: limit, cwd: limit, session: limit };
+	const result: RecentTransitionWindow = [];
+	for (let index = lineage.length - 1; index >= 0; index--) {
+		const record = lineage[index]!;
+		const transitions = record.transitions.filter(({ scope }) => remaining[scope]-- > 0);
+		if (transitions.length) result.push({ ...record, transitions });
+	}
+	return structuredClone(result.reverse());
+}

package/node_modules/@llblab/pi-state-flow/lib/json.ts

@@ -38,6 +38,30 @@ export function canonicalJson(value: JsonValue | unknown): string {
 	return JSON.stringify(orderValue(value));
 }
 
+export function sameJson(left: JsonValue | unknown, right: JsonValue | unknown): boolean {
+	if (left === right) {
+		if (!isJsonValue(left)) throw new Error("Values must be finite, acyclic JSON data");
+		return true;
+	}
+	if (!isJsonValue(left) || !isJsonValue(right)) throw new Error("Values must be finite, acyclic JSON data");
+	return equalJsonValues(left, right);
+}
+
+function equalJsonValues(left: JsonValue, right: JsonValue): boolean {
+	if (left === right) return true;
+	if (Array.isArray(left) || Array.isArray(right)) {
+		return Array.isArray(left) && Array.isArray(right) && left.length === right.length
+			&& left.every((value, index) => equalJsonValues(value, right[index]!));
+	}
+	if (isObject(left) || isObject(right)) {
+		if (!isObject(left) || !isObject(right)) return false;
+		const keys = Object.keys(left);
+		return keys.length === Object.keys(right).length
+			&& keys.every((key) => Object.hasOwn(right, key) && equalJsonValues(left[key]!, right[key]!));
+	}
+	return false;
+}
+
 export function hashJson(value: JsonValue | unknown): string {
 	return createHash("sha256").update(canonicalJson(value)).digest("hex");
 }

package/node_modules/@llblab/pi-state-flow/lib/maintenance.ts

@@ -0,0 +1,141 @@
+import {
+	classifyArtifactFreshness,
+	type ArtifactMetadata,
+	type ArtifactRegistry,
+	type ArtifactSourceIdentity,
+} from "./artifact.ts";
+import type { ArtifactSourceCandidate } from "./discovery.ts";
+import { isObject } from "./json.ts";
+
+export const DEFAULT_ARTIFACT_MAINTENANCE_MAX_READS = 1;
+export const DEFAULT_ARTIFACT_MAINTENANCE_MAX_SOURCE_BYTES = 16 * 1024;
+export const DEFAULT_ARTIFACT_MAINTENANCE_MINIMUM_AGE_MS = 30 * 24 * 60 * 60 * 1_000;
+
+export interface ArtifactMaintenanceOptions {
+	/** Stable cycle time supplied by the caller. */
+	now?: Date | number | string;
+	/** A source must be at least this old. Missing/unparseable timestamps rank as oldest. */
+	minimumAgeMs?: number;
+	/** Strict source-read count ceiling for this cycle. */
+	maxReads?: number;
+	/** Strict source-byte ceiling; bytes conservatively upper-bound source tokenizer input. */
+	maxSourceBytes?: number;
+}
+
+export interface ArtifactMaintenanceRequest extends ArtifactSourceIdentity {
+	reason: "maintenance";
+	sourceBytes: number;
+}
+
+export interface ArtifactMaintenancePlan {
+	requiresCompilation: ArtifactMaintenanceRequest[];
+	deferred: ArtifactMaintenanceRequest[];
+	budget: {
+		maxReads: number;
+		maxSourceBytes: number;
+		usedReads: number;
+		usedSourceBytes: number;
+	};
+}
+
+function nonNegativeSafeInteger(value: number, name: string): number {
+	if (!Number.isSafeInteger(value) || value < 0) throw new Error(`${name} must be a non-negative safe integer`);
+	return value;
+}
+
+function cycleTime(value: Date | number | string | undefined): number {
+	const timestamp = value === undefined
+		? Date.now()
+		: value instanceof Date
+			? value.getTime()
+			: typeof value === "number"
+				? value
+				: Date.parse(value);
+	if (!Number.isFinite(timestamp)) throw new Error("Artifact maintenance cycle time must be valid");
+	return timestamp;
+}
+
+function compiledTime(metadata: ArtifactMetadata): number {
+	if (typeof metadata.compiled_at !== "string") return Number.NEGATIVE_INFINITY;
+	const timestamp = Date.parse(metadata.compiled_at);
+	return Number.isFinite(timestamp) ? timestamp : Number.NEGATIVE_INFINITY;
+}
+
+function request(source: ArtifactSourceCandidate): ArtifactMaintenanceRequest {
+	return {
+		path: source.path,
+		hash: source.hash,
+		reason: "maintenance",
+		sourceBytes: source.bytes,
+	};
+}
+
+/**
+ * Select a bounded, oldest-first maintenance cohort from otherwise fresh artifacts.
+ *
+ * This planner is opt-in and side-effect free. Correctness invalidations remain the
+ * responsibility of planArtifactInvalidation; they are never displaced by maintenance.
+ */
+export function planArtifactMaintenance(
+	sources: readonly ArtifactSourceCandidate[],
+	registry: Readonly<Record<string, unknown>>,
+	compiler: string,
+	options: ArtifactMaintenanceOptions = {},
+): ArtifactMaintenancePlan {
+	if (!isObject(registry)) throw new Error("Artifacts must be a path-keyed JSON object");
+	const now = cycleTime(options.now);
+	const minimumAgeMs = nonNegativeSafeInteger(
+		options.minimumAgeMs ?? DEFAULT_ARTIFACT_MAINTENANCE_MINIMUM_AGE_MS,
+		"Artifact maintenance minimum age",
+	);
+	const maxReads = nonNegativeSafeInteger(
+		options.maxReads ?? DEFAULT_ARTIFACT_MAINTENANCE_MAX_READS,
+		"Artifact maintenance read budget",
+	);
+	const maxSourceBytes = nonNegativeSafeInteger(
+		options.maxSourceBytes ?? DEFAULT_ARTIFACT_MAINTENANCE_MAX_SOURCE_BYTES,
+		"Artifact maintenance source-byte budget",
+	);
+
+	const seen = new Set<string>();
+	const eligible: { source: ArtifactSourceCandidate; compiledAt: number }[] = [];
+	for (const source of sources) {
+		if (seen.has(source.path)) throw new Error(`Duplicate artifact source path: ${source.path}`);
+		seen.add(source.path);
+		nonNegativeSafeInteger(source.bytes, `Artifact source bytes at ${source.path}`);
+		const metadata = Object.hasOwn(registry, source.path) ? registry[source.path] : undefined;
+		const freshness = classifyArtifactFreshness(source, metadata, compiler);
+		if (freshness.kind !== "fresh") continue;
+		const compiledAt = compiledTime(metadata as ArtifactMetadata);
+		if (compiledAt !== Number.NEGATIVE_INFINITY && now - compiledAt < minimumAgeMs) continue;
+		eligible.push({ source, compiledAt });
+	}
+	eligible.sort((left, right) => {
+		if (left.compiledAt !== right.compiledAt) return left.compiledAt - right.compiledAt;
+		return left.source.path < right.source.path ? -1 : left.source.path > right.source.path ? 1 : 0;
+	});
+
+	const requiresCompilation: ArtifactMaintenanceRequest[] = [];
+	const deferred: ArtifactMaintenanceRequest[] = [];
+	let usedSourceBytes = 0;
+	for (const candidate of eligible) {
+		const next = request(candidate.source);
+		if (requiresCompilation.length >= maxReads
+			|| candidate.source.bytes > maxSourceBytes - usedSourceBytes) {
+			deferred.push(next);
+			continue;
+		}
+		requiresCompilation.push(next);
+		usedSourceBytes += candidate.source.bytes;
+	}
+	return {
+		requiresCompilation,
+		deferred,
+		budget: {
+			maxReads,
+			maxSourceBytes,
+			usedReads: requiresCompilation.length,
+			usedSourceBytes,
+		},
+	};
+}

package/node_modules/@llblab/pi-state-flow/lib/memory.ts

@@ -0,0 +1,52 @@
+import { isObject } from "./json.ts";
+import type { MaterializedState, ScopedStates, StateScope } from "./state.ts";
+
+export const MEMORY_PROMOTIONS_KEY = "memory_promotions";
+export const MEMORY_PROMOTION_STATUSES = ["pending", "accepted", "failed", "unknown"] as const;
+export type MemoryPromotionStatus = typeof MEMORY_PROMOTION_STATUSES[number];
+
+export interface MemoryPromotionDiagnostic {
+	id: string;
+	status: MemoryPromotionStatus | "invalid";
+	owner?: string;
+	pointer?: string;
+	revision?: string;
+	error?: string;
+}
+
+function nonEmpty(value: unknown): string | undefined {
+	return typeof value === "string" && value.trim().length > 0 ? value : undefined;
+}
+
+/** Inspect the generic State Flow promotion convention without importing an external owner's schema. */
+export function inspectMemoryPromotions(globalState: MaterializedState): MemoryPromotionDiagnostic[] {
+	const records = globalState.working[MEMORY_PROMOTIONS_KEY];
+	if (records === undefined) return [];
+	if (!isObject(records)) return [{ id: MEMORY_PROMOTIONS_KEY, status: "invalid", error: "promotion registry is not an object" }];
+	return Object.entries(records).sort(([left], [right]) => left.localeCompare(right)).map(([id, value]) => {
+		if (!isObject(value)) return { id, status: "invalid", error: "promotion record is not an object" };
+		const owner = nonEmpty(value.owner);
+		const pointer = nonEmpty(value.pointer);
+		const revision = nonEmpty(value.revision);
+		const error = nonEmpty(value.error);
+		const status = typeof value.status === "string" && (MEMORY_PROMOTION_STATUSES as readonly string[]).includes(value.status)
+			? value.status as MemoryPromotionStatus
+			: undefined;
+		if (!status || !owner) return { id, status: "invalid", ...(owner ? { owner } : {}), ...(pointer ? { pointer } : {}), ...(revision ? { revision } : {}), error: error ?? "promotion status/owner is invalid" };
+		if (status === "accepted" && (!pointer || !revision)) return { id, status: "invalid", owner, ...(pointer ? { pointer } : {}), ...(revision ? { revision } : {}), error: "accepted promotion requires pointer and revision" };
+		return { id, status, owner, ...(pointer ? { pointer } : {}), ...(revision ? { revision } : {}), ...(error ? { error } : {}) };
+	});
+}
+
+function hasSemanticMemory(state: MaterializedState, ignorePromotions: boolean): boolean {
+	if (Object.keys(state.contract).length > 0) return true;
+	return Object.keys(state.working).some((key) => !ignorePromotions || key !== MEMORY_PROMOTIONS_KEY);
+}
+
+export function retainedMemoryScopes(states: ScopedStates): Record<StateScope, boolean> {
+	return {
+		global: hasSemanticMemory(states.global, true),
+		cwd: hasSemanticMemory(states.cwd, false),
+		session: hasSemanticMemory(states.session, false),
+	};
+}

package/node_modules/@llblab/pi-state-flow/lib/migration.ts

@@ -0,0 +1,88 @@
+// Domain: conservative current-snapshot migration planning; Git owns publication and rollback.
+import { randomUUID } from "node:crypto";
+import { join, resolve } from "node:path";
+import {
+	captureOwnedFileBases,
+	cwdScopePaths,
+	parseScopeStream,
+	parseStateSource,
+	serializeScopeStream,
+	sessionScopePaths,
+	type DurableFileBase,
+	type OwnedFileUpdate,
+} from "./durable.ts";
+import type { StateScope } from "./state.ts";
+import type { ScopeStream } from "./temporal.ts";
+
+export interface LegacyStorageMigration {
+	bases: DurableFileBase[];
+	updates: OwnedFileUpdate[];
+	scopes: StateScope[];
+}
+
+/** Read-only activation eligibility, before global migration or any repository publication. */
+export function hasCwdMaterialization(cwd: string, repositoryRoot: string): boolean {
+	const root = resolve(repositoryRoot);
+	const directory = cwdScopePaths(cwd, root).directory;
+	const [legacy, checkpoint, patches] = captureOwnedFileBases([
+		join(directory, "state.json"), join(directory, "checkpoint.json"), join(directory, "patches.jsonl"),
+	], root);
+	if (checkpoint!.content !== undefined) {
+		if (legacy!.content !== undefined) throw new Error(`Ambiguous State Flow storage has both current and checkpoint snapshots: ${directory}`);
+		return parseScopeStream(checkpoint!.content, patches!.content, "cwd", cwd) !== undefined;
+	}
+	if (legacy!.content !== undefined) return parseStateSource(legacy!.content, legacy!.path) !== undefined;
+	if (patches!.content !== undefined) throw new Error(`State Flow tail has no provable snapshot: ${directory}`);
+	return false;
+}
+
+/** Plan from current scope snapshots only; old explanatory journals are never replay input. */
+export function planLegacyStorageMigration(
+	cwd: string,
+	sessionId: string,
+	repositoryRoot: string,
+	origin: string = randomUUID(),
+	sessionKey = sessionId,
+): LegacyStorageMigration {
+	const root = resolve(repositoryRoot);
+	const directories: Record<StateScope, string> = {
+		global: root,
+		cwd: cwdScopePaths(cwd, root).directory,
+		session: sessionScopePaths(cwd, sessionId, root, sessionKey).directory,
+	};
+	const paths = Object.values(directories).flatMap((directory) => [
+		join(directory, "state.json"), join(directory, "checkpoint.json"), join(directory, "patches.jsonl"),
+	]);
+	const bases = captureOwnedFileBases(paths, root);
+	const byPath = new Map(bases.map((base) => [base.path, base]));
+	const updates: OwnedFileUpdate[] = [];
+	const scopes: StateScope[] = [];
+	for (const scope of ["global", "cwd", "session"] as const) {
+		const directory = directories[scope];
+		const legacy = byPath.get(join(directory, "state.json"))!;
+		const checkpoint = byPath.get(join(directory, "checkpoint.json"))!;
+		const patches = byPath.get(join(directory, "patches.jsonl"))!;
+		if (checkpoint.content !== undefined) {
+			if (legacy.content !== undefined) throw new Error(`Ambiguous State Flow storage has both current and checkpoint snapshots: ${directory}`);
+			parseScopeStream(checkpoint.content, patches.content, scope, scope === "cwd" ? cwd : undefined);
+			continue;
+		}
+		if (legacy.content === undefined) {
+			if (patches.content !== undefined) throw new Error(`State Flow tail has no provable snapshot: ${directory}`);
+			continue;
+		}
+		const state = parseStateSource(legacy.content, legacy.path)!;
+		const stream: ScopeStream = {
+			checkpoint: { through: { id: origin, position: 0, parent: null }, state },
+			patches: [],
+		};
+		const source = serializeScopeStream(stream, scope, scope === "cwd" ? cwd : undefined);
+		scopes.push(scope);
+		updates.push(
+			{ path: checkpoint.path, content: source.checkpoint },
+			{ path: patches.path, content: source.patches },
+			{ path: legacy.path },
+		);
+	}
+	return { bases, updates, scopes };
+}