@llblab/pi-kit 0.6.0 → 0.7.1

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

@@ -0,0 +1,296 @@
+import { createHash, randomUUID } from "node:crypto";
+import { closeSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, parse, resolve, sep } from "node:path";
+
+
+export type RemotePublicationMode = "off" | "turn-end" | "transition";
+
+export interface RemotePublicationDestination {
+	gitCommonDir: string;
+	remote: string;
+	ref: string;
+}
+
+export interface RemotePublicationPolicy {
+	mode: RemotePublicationMode;
+	migratedLegacyDefault: boolean;
+}
+
+export interface RemotePublicationPolicyDocument {
+	version: 1;
+	mode: RemotePublicationMode;
+}
+
+/** Missing policy on an existing runtime preserves 0.4 synchronous behavior. */
+export function resolveRemotePublicationPolicy(
+	value: unknown,
+	options: { legacyRuntime: boolean },
+): RemotePublicationPolicy {
+	if (value === undefined) {
+		return options.legacyRuntime
+			? { mode: "transition", migratedLegacyDefault: true }
+			: { mode: "turn-end", migratedLegacyDefault: false };
+	}
+	if (value !== "off" && value !== "turn-end" && value !== "transition") {
+		throw new Error("State Flow remote publication mode must be off, turn-end, or transition");
+	}
+	return { mode: value, migratedLegacyDefault: false };
+}
+
+export function parseRemotePublicationPolicyDocument(
+	value: unknown,
+	options: { legacyRuntime: boolean },
+): RemotePublicationPolicy {
+	if (value === undefined) return resolveRemotePublicationPolicy(undefined, options);
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error("Invalid remote publication policy document");
+	const document = value as Record<string, unknown>;
+	if (Object.keys(document).sort().join(",") !== "mode,version" || document.version !== 1) {
+		throw new Error("Invalid remote publication policy document");
+	}
+	return resolveRemotePublicationPolicy(document.mode, { legacyRuntime: false });
+}
+
+export function serializeRemotePublicationPolicyDocument(policy: RemotePublicationPolicy): RemotePublicationPolicyDocument {
+	return { version: 1, mode: policy.mode };
+}
+
+export function remotePublicationDestinationKey(destination: RemotePublicationDestination): string {
+	if (!destination.remote.trim() || destination.remote !== destination.remote.trim()
+		|| !destination.ref.trim() || destination.ref !== destination.ref.trim()) {
+		throw new Error("Remote publication destination requires non-empty trimmed remote and ref");
+	}
+	return JSON.stringify([resolve(destination.gitCommonDir), destination.remote, destination.ref]);
+}
+
+const COMMIT = /^[0-9a-f]{40,64}$/;
+export type PublicationQueueStatus = "pending" | "pushing" | "failed";
+export interface PublicationQueueState {
+	version: 1;
+	destination: RemotePublicationDestination;
+	target: string;
+	confirmed?: string;
+	status: PublicationQueueStatus;
+	attempt: number;
+	error?: string;
+}
+export type CommitAncestor = (ancestor: string, descendant: string) => boolean;
+
+export function createPublicationQueue(destination: RemotePublicationDestination, target: string): PublicationQueueState {
+	if (!COMMIT.test(target)) throw new Error("Publication queue target must be an exact commit");
+	remotePublicationDestinationKey(destination);
+	return { version: 1, destination: structuredClone(destination), target, status: "pending", attempt: 0 };
+}
+
+export function coalescePublicationTarget(state: PublicationQueueState, destination: RemotePublicationDestination, target: string, isAncestor: CommitAncestor): PublicationQueueState {
+	validatePublicationQueue(state);
+	if (!COMMIT.test(target)) throw new Error("Publication queue target must be an exact commit");
+	if (remotePublicationDestinationKey(state.destination) !== remotePublicationDestinationKey(destination)) throw new Error("Publication queue destination changed");
+	if (target === state.target || isAncestor(target, state.target)) return structuredClone(state);
+	if (!isAncestor(state.target, target)) throw new Error("Publication queue targets diverge");
+	return { ...structuredClone(state), target, status: "pending", attempt: 0, error: undefined };
+}
+
+export function parsePublicationQueue(content: string): PublicationQueueState {
+	let value: unknown;
+	try { value = JSON.parse(content); } catch { throw new Error("Invalid publication queue JSON"); }
+	validatePublicationQueue(value);
+	return structuredClone(value);
+}
+
+export function serializePublicationQueue(state: PublicationQueueState): string {
+	validatePublicationQueue(state);
+	return `${JSON.stringify(state)}\n`;
+}
+
+export function beginPublicationAttempt(state: PublicationQueueState): PublicationQueueState {
+	validatePublicationQueue(state);
+	const { error: _error, ...current } = structuredClone(state);
+	return { ...current, status: "pushing", attempt: state.attempt + 1 };
+}
+
+export function failPublicationAttempt(state: PublicationQueueState, error: string): PublicationQueueState {
+	validatePublicationQueue(state);
+	if (state.status !== "pushing" || !error.trim()) throw new Error("Only an active publication attempt can fail with a bounded error");
+	return { ...structuredClone(state), status: "failed", error: error.trim().slice(0, 1000) };
+}
+
+export function confirmPublicationTarget(state: PublicationQueueState, pushed: string, isAncestor: CommitAncestor): PublicationQueueState | undefined {
+	validatePublicationQueue(state);
+	if (!COMMIT.test(pushed)) throw new Error("Confirmed publication target must be an exact commit");
+	if (pushed === state.target) return undefined;
+	if (!isAncestor(pushed, state.target)) throw new Error("Publication confirmation does not cover the queued lineage");
+	return { ...structuredClone(state), confirmed: pushed, status: "pending", error: undefined };
+}
+
+/** A recovered pushing state is unconfirmed and safely retryable after restart. */
+export function recoverPublicationQueue(state: PublicationQueueState): PublicationQueueState {
+	validatePublicationQueue(state);
+	return state.status === "pushing"
+		? { ...structuredClone(state), status: "pending", error: "previous publication attempt ended without confirmation" }
+		: structuredClone(state);
+}
+
+export function validatePublicationQueue(value: unknown): asserts value is PublicationQueueState {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error("Invalid publication queue document");
+	const v = value as Record<string, unknown>;
+	if (v.version !== 1 || !COMMIT.test(String(v.target)) || !Number.isSafeInteger(v.attempt) || (v.attempt as number) < 0
+		|| (v.status !== "pending" && v.status !== "pushing" && v.status !== "failed")
+		|| typeof v.destination !== "object" || v.destination === null) throw new Error("Invalid publication queue document");
+	remotePublicationDestinationKey(v.destination as unknown as RemotePublicationDestination);
+	if (v.confirmed !== undefined && !COMMIT.test(String(v.confirmed))) throw new Error("Invalid publication queue document");
+	if (v.error !== undefined && (typeof v.error !== "string" || !v.error.trim())) throw new Error("Invalid publication queue document");
+	const allowed = new Set(["version", "destination", "target", "confirmed", "status", "attempt", "error"]);
+	if (Object.keys(v).some((key) => !allowed.has(key))) throw new Error("Invalid publication queue document");
+}
+
+export function publicationQueuePath(destination: RemotePublicationDestination): string {
+	const key = remotePublicationDestinationKey(destination);
+	const name = createHash("sha256").update(key).digest("hex");
+	return resolve(destination.gitCommonDir, "state-flow-publication", `${name}.json`);
+}
+
+function assertNoSymlinkAncestors(path: string): void {
+	const absolute = resolve(path);
+	const root = parse(absolute).root;
+	let current = root;
+	for (const segment of absolute.slice(root.length).split(sep).filter(Boolean)) {
+		current = resolve(current, segment);
+		const stat = lstatSync(current, { throwIfNoEntry: false });
+		if (!stat) break;
+		if (stat.isSymbolicLink()) throw new Error("Publication queue path cannot traverse symlink ancestors");
+		if (!stat.isDirectory()) throw new Error("Publication queue ancestor must be a directory");
+	}
+}
+
+export interface PublicationWorkerLease {
+	path: string;
+	token: string;
+	release(): void;
+}
+
+function processAlive(pid: number): boolean {
+	try { process.kill(pid, 0); return true; }
+	catch (error) { return (error as NodeJS.ErrnoException).code !== "ESRCH"; }
+}
+
+export function acquirePublicationWorkerLease(queuePath: string): PublicationWorkerLease | undefined {
+	const path = `${resolve(queuePath)}.worker.lock`;
+	assertNoSymlinkAncestors(dirname(path));
+	const token = randomUUID();
+	const document = `${JSON.stringify({ version: 1, pid: process.pid, token, startedAt: new Date().toISOString() })}\n`;
+	for (let attempt = 0; attempt < 2; attempt++) {
+		try {
+			writeFileSync(path, document, { flag: "wx", mode: 0o600 });
+			return {
+				path, token,
+				release() {
+					let current: unknown;
+					try { current = JSON.parse(readFileSync(path, "utf8")); } catch { return; }
+					if (typeof current === "object" && current !== null && (current as { token?: unknown }).token === token) rmSync(path, { force: true });
+				},
+			};
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+			let current: unknown;
+			try { current = JSON.parse(readFileSync(path, "utf8")); } catch { throw new Error("Publication worker lease is malformed"); }
+			const pid = typeof current === "object" && current !== null ? (current as { pid?: unknown }).pid : undefined;
+			if (!Number.isSafeInteger(pid) || (pid as number) <= 0) throw new Error("Publication worker lease is malformed");
+			if (processAlive(pid as number)) return undefined;
+			rmSync(path, { force: true });
+		}
+	}
+	return undefined;
+}
+
+export function loadPublicationQueue(path: string): PublicationQueueState | undefined {
+	const target = resolve(path);
+	assertNoSymlinkAncestors(dirname(target));
+	const stat = lstatSync(target, { throwIfNoEntry: false });
+	if (!stat) return undefined;
+	if (!stat.isFile()) throw new Error("Publication queue path must be a regular file");
+	return parsePublicationQueue(readFileSync(target, "utf8"));
+}
+
+export function removePublicationQueue(path: string, expected: PublicationQueueState): void {
+	const target = resolve(path);
+	assertNoSymlinkAncestors(dirname(target));
+	const lock = `${target}.lock`;
+	let lockFd: number | undefined;
+	try {
+		lockFd = openSync(lock, "wx", 0o600);
+		const current = loadPublicationQueue(target);
+		if (!current || serializePublicationQueue(current) !== serializePublicationQueue(expected)) {
+			throw new Error("Publication queue compare-and-swap conflict");
+		}
+		rmSync(target);
+	} finally {
+		if (lockFd !== undefined) {
+			closeSync(lockFd);
+			rmSync(lock, { force: true });
+		}
+	}
+}
+
+export interface PublicationQueueReceipt {
+	previous?: PublicationQueueState;
+	current: PublicationQueueState;
+}
+
+export function savePublicationQueue(path: string, state: PublicationQueueState, expected?: PublicationQueueState): PublicationQueueReceipt {
+	const target = resolve(path);
+	assertNoSymlinkAncestors(dirname(target));
+	mkdirSync(dirname(target), { recursive: true });
+	const lock = `${target}.lock`;
+	let lockFd: number | undefined;
+	try {
+		lockFd = openSync(lock, "wx", 0o600);
+		const existing = lstatSync(target, { throwIfNoEntry: false });
+		if (existing && !existing.isFile()) throw new Error("Publication queue path must be a regular file");
+		const previous = existing ? parsePublicationQueue(readFileSync(target, "utf8")) : undefined;
+		if (expected !== undefined && (previous === undefined
+			|| serializePublicationQueue(previous) !== serializePublicationQueue(expected))) {
+			throw new Error("Publication queue compare-and-swap conflict");
+		}
+		if (expected === undefined && previous !== undefined) throw new Error("Publication queue compare-and-swap requires the current receipt");
+		const temporary = `${target}.tmp-${process.pid}-${Date.now()}`;
+		try {
+			writeFileSync(temporary, serializePublicationQueue(state), { flag: "wx", mode: 0o600 });
+			renameSync(temporary, target);
+		} finally {
+			rmSync(temporary, { force: true });
+		}
+		return { ...(previous === undefined ? {} : { previous }), current: structuredClone(state) };
+	} finally {
+		if (lockFd !== undefined) {
+			closeSync(lockFd);
+			rmSync(lock, { force: true });
+		}
+	}
+}
+
+export type PublicationPush = (state: Readonly<PublicationQueueState>) => Promise<void>;
+
+export interface PublicationWorkerResult {
+	attempted: PublicationQueueState;
+	next?: PublicationQueueState;
+}
+
+/** Execute one immutable target attempt; persistence/CAS remains the caller's responsibility. */
+export async function runPublicationWorker(
+	state: PublicationQueueState,
+	push: PublicationPush,
+	current: () => PublicationQueueState,
+	isAncestor: CommitAncestor,
+): Promise<PublicationWorkerResult> {
+	const attempted = beginPublicationAttempt(state);
+	try {
+		await push(Object.freeze(structuredClone(attempted)));
+		const next = confirmPublicationTarget(current(), attempted.target, isAncestor);
+		return { attempted, ...(next === undefined ? {} : { next }) };
+	} catch (error) {
+		return {
+			attempted,
+			next: failPublicationAttempt(attempted, error instanceof Error ? error.message : String(error)),
+		};
+	}
+}

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

@@ -1,26 +1,42 @@
-import { emptyState } from "./state.ts";
-import { migrateSnapshot, migrationFailure, type Snapshot } from "./snapshot.ts";
+import { RevisionUnavailableError, emptySnapshot, parsePiCheckpoint, migrationFailure, type Snapshot } from "./snapshot.ts";
 
 export interface SnapshotRecovery {
 	snapshot: Snapshot;
 	skipped: string[];
+	disabledMarker?: true;
 }
 
 function failureMessage(snapshot: Snapshot): string | undefined {
-	return !snapshot.enabled && snapshot.validation?.attempt === 0
-		? snapshot.validation.error
+	return !snapshot.config.enabled && snapshot.meta.validation?.attempt === 0
+		? snapshot.meta.validation.error
 		: undefined;
 }
 
 /** Recover the newest valid snapshot, falling back through the active branch. */
-export function recoverSnapshot(candidates: readonly unknown[]): SnapshotRecovery {
+export function recoverSnapshot(candidates: readonly unknown[], resolveRevision?: (revision: string, legacy?: Snapshot) => Snapshot): SnapshotRecovery {
 	const skipped: string[] = [];
 	let newestFailure: Snapshot | undefined;
 	for (const candidate of candidates) {
 		let migrated: Snapshot;
+		let selectedRevision: string | undefined;
 		try {
-			migrated = migrateSnapshot(candidate);
+			const parsed = parsePiCheckpoint(candidate);
+			if ("revision" in parsed) {
+				selectedRevision = parsed.revision;
+				if (!resolveRevision) throw new Error("Checkpoint pointer requires immutable runtime resolution");
+				return { snapshot: resolveRevision(parsed.revision), skipped };
+			}
+			if ("disabled" in parsed) return { snapshot: emptySnapshot(), skipped, disabledMarker: true };
+			migrated = parsed;
+			if (failureMessage(migrated) === undefined && migrated.meta.durableBase) {
+				selectedRevision = migrated.meta.durableBase;
+				if (!resolveRevision) throw new Error("Legacy checkpoint requires immutable runtime resolution");
+				return { snapshot: resolveRevision(migrated.meta.durableBase, migrated), skipped };
+			}
 		} catch (error) {
+			if (selectedRevision && error instanceof RevisionUnavailableError) {
+				return { snapshot: migrationFailure({ meta: { durableBase: selectedRevision } }, `Snapshot restoration failed: ${error.message}`), skipped };
+			}
 			migrated = migrationFailure(
 				{},
 				`Snapshot restoration failed: ${error instanceof Error ? error.message : String(error)}`,
@@ -32,7 +48,7 @@ export function recoverSnapshot(candidates: readonly unknown[]): SnapshotRecover
 		skipped.push(failure);
 	}
 	return {
-		snapshot: newestFailure ?? { enabled: false, state: emptyState(), step: 0 },
+		snapshot: newestFailure ?? emptySnapshot(),
 		skipped,
 	};
 }

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

@@ -0,0 +1,79 @@
+import {
+	decideArtifactAcquisition,
+	type ArtifactAcquisitionIntent,
+	type ArtifactAcquisitionReason,
+} from "./acquisition.ts";
+import type { ArtifactSourceIdentity } from "./artifact.ts";
+import type { StateScope } from "./state.ts";
+
+export type RehydrationPhase = "resume-bootstrap" | "new-bootstrap" | "step";
+
+export interface RehydrationRoute {
+	scope: StateScope;
+	source: ArtifactSourceIdentity;
+	metadata: unknown;
+	compiler: string;
+	intent: ArtifactAcquisitionIntent;
+	materializedSufficient?: boolean;
+	explicitRefresh?: boolean;
+	sourceBytes?: number;
+}
+
+export interface RehydrationRead {
+	scope: StateScope;
+	path: string;
+	hash: string;
+	reason: ArtifactAcquisitionReason;
+}
+
+export interface RehydrationPlan {
+	reads: RehydrationRead[];
+	materialized: string[];
+	deferred: Array<{ path: string; reason: "new-session-scope" | "read-count-limit" | "source-byte-limit" }>;
+}
+
+export interface RehydrationOptions {
+	maxReads?: number;
+	maxSourceBytes?: number;
+}
+
+/** Plan visible reads only; this function never reads, compiles, mutates, or publishes sources. */
+export function planKnowledgeRehydration(
+	phase: RehydrationPhase,
+	routes: readonly RehydrationRoute[],
+	options: RehydrationOptions = {},
+): RehydrationPlan {
+	const maxReads = Math.max(0, Math.floor(options.maxReads ?? 1));
+	const maxSourceBytes = Math.max(0, Math.floor(options.maxSourceBytes ?? 64 * 1024));
+	const reads: RehydrationRead[] = [];
+	const materialized: string[] = [];
+	const deferred: RehydrationPlan["deferred"] = [];
+	let sourceBytes = 0;
+	for (const route of [...routes].sort((left, right) => left.source.path.localeCompare(right.source.path))) {
+		if (phase === "new-bootstrap" && route.scope === "session") {
+			deferred.push({ path: route.source.path, reason: "new-session-scope" });
+			continue;
+		}
+		const decision = decideArtifactAcquisition(route.source, route.metadata, route.compiler, {
+			intent: route.intent,
+			...(route.materializedSufficient === undefined ? {} : { materializedSufficient: route.materializedSufficient }),
+			...(route.explicitRefresh === undefined ? {} : { explicitRefresh: route.explicitRefresh }),
+		});
+		if (decision.kind === "use-materialized") {
+			materialized.push(route.source.path);
+			continue;
+		}
+		if (reads.length >= maxReads) {
+			deferred.push({ path: route.source.path, reason: "read-count-limit" });
+			continue;
+		}
+		const bytes = route.sourceBytes ?? 0;
+		if (sourceBytes + bytes > maxSourceBytes) {
+			deferred.push({ path: route.source.path, reason: "source-byte-limit" });
+			continue;
+		}
+		sourceBytes += bytes;
+		reads.push({ scope: route.scope, path: route.source.path, hash: route.source.hash, reason: decision.reason });
+	}
+	return { reads, materialized, deferred };
+}