@llblab/pi-kit 0.18.1 → 0.19.0

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

@@ -1,147 +0,0 @@
-import {
-	classifyArtifactFreshness,
-	type ArtifactMetadata,
-	type ArtifactProvenance,
-	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(entry: ArtifactProvenance | undefined, legacy: unknown): number {
-	const timestamp = entry?.malformed === true ? undefined
-		: entry !== undefined && Object.hasOwn(entry, "compiledAt") ? entry.compiledAt
-			: legacy;
-	if (typeof timestamp !== "string") return Number.NEGATIVE_INFINITY;
-	const parsed = Date.parse(timestamp);
-	return Number.isFinite(parsed) ? parsed : 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 = {},
-	provenance: Readonly<Record<string, ArtifactProvenance>> = {},
-): 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 entry = Object.hasOwn(provenance, source.path) ? provenance[source.path] : undefined;
-		const freshness = classifyArtifactFreshness(source, metadata, compiler, false, entry);
-		if (freshness.kind !== "fresh") continue;
-		const compiledAt = compiledTime(entry, isObject(metadata) ? (metadata as ArtifactMetadata).compiled_at : undefined);
-		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/migration.ts

@@ -1,171 +0,0 @@
-// Domain: predecessor temporal-envelope migration planning; Git/files backends own publication and rollback.
-import { lstatSync, readFileSync, readdirSync } from "node:fs";
-import { join, resolve } from "node:path";
-import {
-	captureOwnedFileBases,
-	cwdScopePaths,
-	parseScopeStream,
-	serializeScopeMetadata,
-	serializeScopeStream,
-	sessionScopeKey,
-	sessionScopePaths,
-	type DurableFileBase,
-	type OwnedFileUpdate,
-} from "./durable.ts";
-import { parseSessionRuntime, serializeSessionRuntime } from "./snapshot.ts";
-import { migratePreIntentState, type StateScope } from "./state.ts";
-
-export interface LegacyStorageMigration {
-	bases: DurableFileBase[];
-	updates: OwnedFileUpdate[];
-	scopes: StateScope[];
-}
-
-interface MigrationDirectory {
-	directory: string;
-	scope: StateScope;
-	cwdIdentity?: string;
-	sessionId?: string;
-}
-
-/** Discover every owner-proven CWD and session cohort beneath the configured store. */
-function migrationDirectories(cwd: string, sessionId: string, root: string, sessionKey: string): MigrationDirectory[] {
-	const selectedCwd = cwdScopePaths(cwd, root).directory;
-	const selectedSession = sessionScopePaths(cwd, sessionId, root, sessionKey).directory;
-	const directories: MigrationDirectory[] = [{ directory: root, scope: "global" }];
-	const cwdOwners = new Map<string, string>([[selectedCwd, resolve(cwd)]]);
-	if (lstatSync(root, { throwIfNoEntry: false }) !== undefined) {
-		for (const entry of readdirSync(root, { withFileTypes: true })) {
-			if (!entry.isDirectory()) continue;
-			const directory = join(root, entry.name);
-			let checkpoint: unknown;
-			let meta: unknown;
-			try { checkpoint = JSON.parse(readFileSync(join(directory, "checkpoint.json"), "utf8")); }
-			catch { continue; }
-			try { meta = JSON.parse(readFileSync(join(directory, "meta.json"), "utf8")); } catch { /* predecessor metadata may be absent */ }
-			const owner = checkpoint && typeof checkpoint === "object" && !Array.isArray(checkpoint) && (checkpoint as { owner?: unknown }).owner
-				? (checkpoint as { owner: { cwd?: unknown } }).owner
-				: meta && typeof meta === "object" && !Array.isArray(meta) ? (meta as { owner?: { cwd?: unknown } }).owner : undefined;
-			if (owner && typeof owner.cwd === "string" && resolve(owner.cwd) === owner.cwd) cwdOwners.set(directory, owner.cwd);
-		}
-	}
-	for (const [cwdDirectory, cwdOwner] of cwdOwners) {
-		directories.push({ directory: cwdDirectory, scope: "cwd", cwdIdentity: cwdOwner });
-		if (lstatSync(cwdDirectory, { throwIfNoEntry: false }) === undefined) continue;
-		for (const entry of readdirSync(cwdDirectory, { withFileTypes: true })) {
-			if (!entry.isDirectory()) continue;
-			try { sessionScopeKey(entry.name); } catch { continue; }
-			const directory = join(cwdDirectory, entry.name);
-			let meta: unknown;
-			let runtime: unknown;
-			try { meta = JSON.parse(readFileSync(join(directory, "meta.json"), "utf8")); }
-			catch { continue; }
-			try { runtime = JSON.parse(readFileSync(join(directory, "runtime.json"), "utf8")); }
-			catch { /* predecessor sessions keep identity in meta.json */ }
-			const identity = meta && typeof meta === "object" && !Array.isArray(meta) && (meta as { identity?: unknown }).identity !== undefined
-				? (meta as { identity?: unknown }).identity
-				: runtime && typeof runtime === "object" && !Array.isArray(runtime) ? (runtime as { identity?: unknown }).identity : undefined;
-			if (!identity || typeof identity !== "object" || Array.isArray(identity)) continue;
-			const owner = identity as { cwd?: unknown; sessionId?: unknown };
-			if (owner.cwd === cwdOwner && typeof owner.sessionId === "string" && owner.sessionId.length > 0) {
-				directories.push({ directory, scope: "session", cwdIdentity: cwdOwner, sessionId: owner.sessionId });
-			}
-		}
-	}
-	if (!directories.some(({ directory }) => directory === selectedSession)) {
-		directories.push({ directory: selectedSession, scope: "session", cwdIdentity: resolve(cwd), sessionId });
-	}
-	return directories;
-}
-
-/** 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 [checkpoint, patches, meta] = captureOwnedFileBases([
-		join(directory, "checkpoint.json"), join(directory, "patches.jsonl"), join(directory, "meta.json"),
-	], root);
-	if (checkpoint!.content !== undefined) return parseScopeStream(checkpoint!.content, patches!.content, "cwd", cwd, meta!.content) !== undefined;
-	if (patches!.content !== undefined) throw new Error(`State Flow tail has no provable checkpoint: ${directory}`);
-	return false;
-}
-
-function checkpointNeedsIntentMigration(source: string): boolean {
-	const checkpoint = JSON.parse(source) as unknown;
-	if (migratePreIntentState(checkpoint) !== undefined) return true;
-	return checkpoint !== null && typeof checkpoint === "object" && !Array.isArray(checkpoint)
-		&& migratePreIntentState((checkpoint as { state?: unknown }).state) !== undefined;
-}
-
-/** Detect predecessor snapshots, temporal envelopes, or pre-intents semantic states without mutating the store. */
-export function hasLegacyStateSources(
-	cwd: string,
-	sessionId: string,
-	repositoryRoot: string,
-	sessionKey = sessionId,
-): boolean {
-	const root = resolve(repositoryRoot);
-	return migrationDirectories(cwd, sessionId, root, sessionKey).some(({ directory, scope }) => {
-		const checkpointPath = join(directory, "checkpoint.json");
-		if (lstatSync(checkpointPath, { throwIfNoEntry: false }) === undefined) return false;
-		try {
-			if (checkpointNeedsIntentMigration(readFileSync(checkpointPath, "utf8"))) return true;
-			const meta = JSON.parse(readFileSync(join(directory, "meta.json"), "utf8"));
-			if (meta === null || typeof meta !== "object" || !("temporal" in meta)) return true;
-			return scope === "session"
-				&& lstatSync(join(directory, "runtime.json"), { throwIfNoEntry: false }) === undefined
-				&& ("identity" in meta || "lineage" in meta);
-		} catch { return true; }
-	});
-}
-
-/** Plan from current scope snapshots only; old explanatory journals are never replay input. */
-export function planLegacyStorageMigration(
-	cwd: string,
-	sessionId: string,
-	repositoryRoot: string,
-	_origin?: string,
-	sessionKey = sessionId,
-): LegacyStorageMigration {
-	const root = resolve(repositoryRoot);
-	const directories = migrationDirectories(cwd, sessionId, root, sessionKey);
-	const paths = directories.flatMap(({ directory, scope }) => [
-		join(directory, "checkpoint.json"), join(directory, "patches.jsonl"), join(directory, "meta.json"),
-		...(scope === "session" ? [join(directory, "config.json"), join(directory, "runtime.json")] : []),
-	]);
-	const bases = captureOwnedFileBases(paths, root);
-	const byPath = new Map(bases.map((base) => [base.path, base]));
-	const updates: OwnedFileUpdate[] = [];
-	const scopes: StateScope[] = [];
-	for (const { scope, directory, cwdIdentity, sessionId: ownedSessionId } of directories) {
-		const checkpoint = byPath.get(join(directory, "checkpoint.json"))!;
-		const patches = byPath.get(join(directory, "patches.jsonl"))!;
-		const meta = byPath.get(join(directory, "meta.json"))!;
-		if (checkpoint.content !== undefined) {
-			const stream = parseScopeStream(checkpoint.content, patches.content, scope, scope === "cwd" ? cwdIdentity : undefined, meta.content)!;
-			const source = serializeScopeStream(stream, scope, scope === "cwd" ? cwdIdentity : undefined);
-			const metadata = serializeScopeMetadata(undefined, stream, scope, scope === "cwd" ? cwdIdentity : undefined, meta.content);
-			const cohortUpdates: OwnedFileUpdate[] = [
-				...(checkpoint.content === source.checkpoint ? [] : [{ path: checkpoint.path, content: source.checkpoint }]),
-				...(patches.content === source.patches ? [] : [{ path: patches.path, content: source.patches }]),
-				...(meta.content === metadata ? [] : [{ path: meta.path, content: metadata }]),
-			];
-			if (scope === "session") {
-				const config = byPath.get(join(directory, "config.json"))!;
-				const runtimeFile = byPath.get(join(directory, "runtime.json"))!;
-				const runtime = parseSessionRuntime(config.content, runtimeFile.content, cwdIdentity!, ownedSessionId!, meta.content);
-				if (runtime !== undefined) {
-					const serialized = serializeSessionRuntime(runtime, cwdIdentity!, ownedSessionId!);
-					if (runtimeFile.content !== serialized.runtime) cohortUpdates.push({ path: runtimeFile.path, content: serialized.runtime });
-				}
-			}
-			if (cohortUpdates.length > 0) {
-				if (!scopes.includes(scope)) scopes.push(scope);
-				updates.push(...cohortUpdates);
-			}
-			continue;
-		}
-		if (patches.content !== undefined) throw new Error(`State Flow tail has no provable checkpoint: ${directory}`);
-	}
-	return { bases, updates, scopes };
-}