@sayknow-cli/coding-agent 0.4.7 → 0.5.0

package/src/session/internal/native-publish-outcome.ts

@@ -0,0 +1,271 @@
+export type NativePublishMutationState = "not_committed" | "committed" | "unknown";
+export type NativePublishDurabilityState = "not_attempted" | "proven" | "not_provable";
+export type NativePublishReason =
+	| "none"
+	| "destination_exists"
+	| "atomic_unavailable"
+	| "cross_device"
+	| "permission_denied"
+	| "io_failure"
+	| "interrupted"
+	| "invalid_request"
+	| "identity_violation"
+	| "durability_not_provable"
+	| "unknown";
+export type NativePublishOperation = "direct_rename" | "retained_file" | "retained_tree";
+
+export type NativePublishPrimitive =
+	| "renameat2_noreplace"
+	| "renameatx_np_excl"
+	| "windows_rename_noreplace"
+	| "unsupported"
+	| "unknown";
+export type NativePublishPhase =
+	| "preflight"
+	| "file_sync"
+	| "rename"
+	| "source_parent_sync"
+	| "destination_parent_sync"
+	| "terminal_identity"
+	| "complete"
+	| "unknown";
+
+type SyncFailure = {
+	phase: Exclude<NativePublishPhase, "preflight" | "file_sync" | "rename" | "complete" | "unknown">;
+	parentRole: "source" | "destination" | "shared" | "staged_file";
+	osCode?: number;
+	kind: "unsupported" | "io" | "permission" | "other";
+};
+
+type PublishDiagnostic = {
+	schemaVersion: 1;
+	collectionState: "complete" | "partial" | "unavailable";
+	osCode?: number;
+	syncFailures?: readonly SyncFailure[];
+};
+
+export type NativePublishIdentity = {
+	readonly dev: string;
+	readonly ino: string;
+	readonly size: string;
+	readonly mtimeNs: string;
+	readonly ctimeNs: string;
+	readonly sha256?: string;
+};
+
+export type NativePublishOutcome = {
+	readonly ok: boolean;
+	readonly code?: string;
+	readonly identity?: NativePublishIdentity;
+	readonly mutationState: NativePublishMutationState;
+	readonly durabilityState: NativePublishDurabilityState;
+	readonly reason: NativePublishReason;
+	readonly primitive: NativePublishPrimitive;
+	readonly phase: NativePublishPhase;
+	readonly diagnostic: PublishDiagnostic;
+};
+
+const mutationStates = new Set<NativePublishMutationState>(["not_committed", "committed", "unknown"]);
+const durabilityStates = new Set<NativePublishDurabilityState>(["not_attempted", "proven", "not_provable"]);
+const reasons = new Set<NativePublishReason>([
+	"none",
+	"destination_exists",
+	"atomic_unavailable",
+	"cross_device",
+	"permission_denied",
+	"io_failure",
+	"interrupted",
+	"invalid_request",
+	"identity_violation",
+	"durability_not_provable",
+	"unknown",
+]);
+const primitives = new Set<NativePublishPrimitive>([
+	"renameat2_noreplace",
+	"renameatx_np_excl",
+	"windows_rename_noreplace",
+	"unsupported",
+	"unknown",
+]);
+const phases = new Set<NativePublishPhase>([
+	"preflight",
+	"file_sync",
+	"rename",
+	"source_parent_sync",
+	"destination_parent_sync",
+	"terminal_identity",
+	"complete",
+	"unknown",
+]);
+const preMutationReasons = new Set<NativePublishReason>([
+	"destination_exists",
+	"atomic_unavailable",
+	"cross_device",
+	"permission_denied",
+	"io_failure",
+	"interrupted",
+	"invalid_request",
+	"identity_violation",
+]);
+const int32 = (value: unknown): value is number =>
+	typeof value === "number" && Number.isInteger(value) && value >= -2147483648 && value <= 2147483647;
+const ownPlainRecord = (value: unknown): value is Record<string, unknown> =>
+	Boolean(value) && typeof value === "object" && Object.getPrototypeOf(value) === Object.prototype;
+const exactKeys = (value: Record<string, unknown>, keys: readonly string[]) =>
+	Object.keys(value).every(key => keys.includes(key));
+
+const malformed: NativePublishOutcome = Object.freeze({
+	ok: false,
+	mutationState: "unknown",
+	durabilityState: "not_provable",
+	reason: "unknown",
+	primitive: "unknown",
+	phase: "unknown",
+	diagnostic: Object.freeze({ schemaVersion: 1, collectionState: "unavailable" }),
+});
+
+function validIdentity(value: unknown): boolean {
+	if (value === undefined) return true;
+	if (!ownPlainRecord(value) || !exactKeys(value, ["dev", "ino", "size", "mtimeNs", "ctimeNs", "sha256"]))
+		return false;
+	const decimal = (field: unknown) => typeof field === "string" && /^-?[0-9]{1,32}$/.test(field);
+	return (
+		decimal(value.dev) &&
+		decimal(value.ino) &&
+		decimal(value.size) &&
+		decimal(value.mtimeNs) &&
+		decimal(value.ctimeNs) &&
+		(value.sha256 === undefined || (typeof value.sha256 === "string" && /^[a-f0-9]{64}$/.test(value.sha256)))
+	);
+}
+
+function validDiagnostic(value: unknown): value is PublishDiagnostic {
+	if (!ownPlainRecord(value) || !exactKeys(value, ["schemaVersion", "collectionState", "osCode", "syncFailures"]))
+		return false;
+	if (value.schemaVersion !== 1 || !["complete", "partial", "unavailable"].includes(value.collectionState as string))
+		return false;
+	if (value.osCode !== undefined && !int32(value.osCode)) return false;
+	if (value.syncFailures === undefined) return true;
+	if (!Array.isArray(value.syncFailures) || value.syncFailures.length > 4) return false;
+	return value.syncFailures.every(failure => {
+		if (!ownPlainRecord(failure) || !exactKeys(failure, ["phase", "parentRole", "osCode", "kind"])) return false;
+		const phase = failure.phase;
+		const role = failure.parentRole;
+		const compatibleRole =
+			(phase === "source_parent_sync" && ["source", "shared"].includes(role as string)) ||
+			(phase === "destination_parent_sync" && role === "destination") ||
+			(phase === "terminal_identity" && ["source", "destination", "shared", "staged_file"].includes(role as string));
+		return (
+			["source_parent_sync", "destination_parent_sync", "terminal_identity"].includes(phase as string) &&
+			compatibleRole &&
+			(failure.osCode === undefined || int32(failure.osCode)) &&
+			["unsupported", "io", "permission", "other"].includes(failure.kind as string)
+		);
+	});
+}
+
+function legalOutcome(outcome: NativePublishOutcome): boolean {
+	if (outcome.mutationState === "not_committed")
+		return (
+			!outcome.ok &&
+			outcome.durabilityState === "not_attempted" &&
+			preMutationReasons.has(outcome.reason) &&
+			((outcome.phase === "rename" &&
+				[
+					"destination_exists",
+					"atomic_unavailable",
+					"cross_device",
+					"permission_denied",
+					"io_failure",
+					"interrupted",
+				].includes(outcome.reason)) ||
+				(outcome.phase === "preflight" &&
+					!["atomic_unavailable", "cross_device", "interrupted"].includes(outcome.reason)) ||
+				(outcome.phase === "file_sync" && outcome.reason === "io_failure"))
+		);
+	if (outcome.mutationState === "unknown")
+		return (
+			!outcome.ok &&
+			outcome.durabilityState === "not_provable" &&
+			outcome.reason === "unknown" &&
+			["rename", "terminal_identity"].includes(outcome.phase)
+		);
+	if (outcome.ok)
+		return (
+			outcome.reason === "none" &&
+			outcome.phase === "complete" &&
+			["proven", "not_attempted"].includes(outcome.durabilityState)
+		);
+	return (
+		!outcome.ok &&
+		outcome.durabilityState === "not_provable" &&
+		((outcome.reason === "durability_not_provable" &&
+			["file_sync", "source_parent_sync", "destination_parent_sync"].includes(outcome.phase)) ||
+			(outcome.reason === "identity_violation" && outcome.phase === "terminal_identity") ||
+			(outcome.reason === "io_failure" && outcome.phase === "terminal_identity"))
+	);
+}
+
+/**
+ * Treat incompatible native results as an unknown mutation; never infer safety from legacy fields.
+ * Retained descriptor operations have a stricter contract than direct rename: a reported success
+ * includes the terminal identity and all required durability evidence.
+ */
+export function classifyNativePublishOutcome(
+	value: unknown,
+	operation: NativePublishOperation = "direct_rename",
+): NativePublishOutcome {
+	if (
+		!ownPlainRecord(value) ||
+		!exactKeys(value, [
+			"ok",
+			"code",
+			"identity",
+			"mutationState",
+			"durabilityState",
+			"reason",
+			"primitive",
+			"phase",
+			"diagnostic",
+		])
+	)
+		return malformed;
+	if (
+		typeof value.ok !== "boolean" ||
+		(value.code !== undefined && (typeof value.code !== "string" || !/^[a-z0-9_]{1,64}$/.test(value.code))) ||
+		!mutationStates.has(value.mutationState as NativePublishMutationState) ||
+		!durabilityStates.has(value.durabilityState as NativePublishDurabilityState) ||
+		!reasons.has(value.reason as NativePublishReason) ||
+		!primitives.has(value.primitive as NativePublishPrimitive) ||
+		!phases.has(value.phase as NativePublishPhase) ||
+		!validIdentity(value.identity) ||
+		!validDiagnostic(value.diagnostic)
+	)
+		return malformed;
+	const outcome = value as unknown as NativePublishOutcome;
+	if (!legalOutcome(outcome)) return malformed;
+	if (operation === "direct_rename") return outcome;
+	if (
+		outcome.primitive !== "renameat2_noreplace" ||
+		(outcome.ok && (!outcome.identity || outcome.durabilityState !== "proven" || outcome.phase !== "complete"))
+	)
+		return malformed;
+	return outcome;
+}
+
+/** Only a fully validated pre-mutation result permits exact cleanup of current staging. */
+export function mayCleanCurrentStaging(outcome: NativePublishOutcome): boolean {
+	return outcome.mutationState === "not_committed" && outcome.durabilityState === "not_attempted";
+}
+
+/** Stable, bounded text for startup errors. Native paths and messages are intentionally excluded. */
+export function formatNativePublishDiagnostic(outcome: NativePublishOutcome): string {
+	const osCode = outcome.diagnostic.osCode === undefined ? "" : ` os=${outcome.diagnostic.osCode}`;
+	const failures = outcome.diagnostic.syncFailures
+		?.map(
+			failure =>
+				`${failure.parentRole}:${failure.phase}:${failure.kind}${failure.osCode === undefined ? "" : `:${failure.osCode}`}`,
+		)
+		.join(",");
+	return `${outcome.reason} primitive=${outcome.primitive} phase=${outcome.phase}${osCode}${failures ? ` sync=${failures}` : ""}`;
+}

package/src/session/memory-guard-checkpoint-participant.ts

@@ -0,0 +1,131 @@
+import * as crypto from "node:crypto";
+import * as path from "node:path";
+import type { RecoveryFsRoot } from "@sayknow-cli/natives";
+import type {
+	RecoveryHydrationContext,
+	ResumeSessionIdentity,
+	SessionDestinationInput,
+	SessionManager,
+	SessionManagerCheckpointRevisionStrings,
+	StrictSessionOpenFailure,
+} from "./session-manager";
+
+export interface MemoryGuardTranscriptDescriptorV1 {
+	bytes: string;
+	relative_path: string;
+	sha256: string;
+}
+
+export interface MemoryGuardCheckpointBlobAuthorityV1 {
+	kind: "checkpoint_blob_tree_v1";
+	manifest_relative_path: string;
+	manifest_sha256: string;
+	root_relative_path: string;
+}
+
+export interface MemoryGuardCheckpointBlobManifestEntryV1 {
+	bytes: string;
+	relative_path: string;
+	sha256: string;
+}
+
+export interface MemoryGuardCheckpointBlobManifestV1 {
+	entries: MemoryGuardCheckpointBlobManifestEntryV1[];
+	schema_version: 1;
+}
+
+export interface MemoryGuardSessionManagerCheckpointV1 {
+	blob_authority: MemoryGuardCheckpointBlobAuthorityV1;
+	revisions: SessionManagerCheckpointRevisionStrings;
+	schema_version: 1;
+	session_id: string;
+	session_name: string | null;
+	transcript: MemoryGuardTranscriptDescriptorV1;
+}
+
+export interface MemoryGuardParticipantDescriptorV1 {
+	ordinal: number;
+	checkpoint: MemoryGuardCheckpointBlobAuthorityV1;
+	revisions: SessionManagerCheckpointRevisionStrings;
+	session_id: string;
+	session_name: string | null;
+	transcript: MemoryGuardTranscriptDescriptorV1;
+}
+
+export interface MemoryGuardParticipantIngressLease {
+	readonly token: symbol;
+	release(): void;
+}
+
+export interface MemoryGuardCreateCheckpointInput {
+	ingressLease: MemoryGuardParticipantIngressLease;
+	checkpointRoot: string;
+}
+
+export type MemoryGuardRestoreBlockedReason =
+	| StrictSessionOpenFailure["reason"]
+	| "checkpoint-mismatch"
+	| "participant-mismatch"
+	| "transcript-mismatch"
+	| "blob-manifest-mismatch"
+	| "blob-missing"
+	| "blob-hash-mismatch"
+	| "blob-authority-mismatch"
+	| "destination-unavailable";
+
+export interface MemoryGuardRestoreInput {
+	incidentAuthority: RecoveryFsRoot;
+	participant: MemoryGuardParticipantDescriptorV1;
+	checkpoint: MemoryGuardSessionManagerCheckpointV1;
+	destination: SessionDestinationInput;
+}
+
+export type MemoryGuardRestoreResult =
+	| {
+			kind: "staged";
+			manager: SessionManager;
+			hydrationContext: RecoveryHydrationContext;
+			transcriptIdentity: ResumeSessionIdentity;
+			cleanup: () => Promise<void>;
+	  }
+	| { kind: "blocked"; reason: MemoryGuardRestoreBlockedReason };
+
+function sortJson(value: unknown): unknown {
+	if (Array.isArray(value)) return value.map(sortJson);
+	if (value && typeof value === "object") {
+		return Object.fromEntries(
+			Object.entries(value as Record<string, unknown>)
+				.sort(([left], [right]) => left.localeCompare(right))
+				.map(([key, child]) => [key, sortJson(child)]),
+		);
+	}
+	return value;
+}
+
+export function memoryGuardCanonicalJson(value: unknown): string {
+	return `${JSON.stringify(sortJson(value))}\n`;
+}
+
+export function memoryGuardSha256Hex(value: Uint8Array | string): string {
+	return crypto.createHash("sha256").update(value).digest("hex");
+}
+
+export function isMemoryGuardDecimalString(value: unknown): value is string {
+	return typeof value === "string" && /^(?:0|[1-9]\d*)$/.test(value);
+}
+
+export function isMemoryGuardSha256Hex(value: unknown): value is string {
+	return typeof value === "string" && /^[0-9a-f]{64}$/.test(value);
+}
+
+export function isMemoryGuardRelativePath(value: unknown): value is string {
+	if (typeof value !== "string" || value.length === 0) return false;
+	if (path.isAbsolute(value) || value.includes("\\")) return false;
+	const parts = value.split("/");
+	return parts.every(part => part.length > 0 && part !== "." && part !== "..");
+}
+
+export function hasOnlyKeys(value: Record<string, unknown>, allowed: readonly string[]): boolean {
+	const keys = Object.keys(value);
+	return keys.length === allowed.length && keys.every(key => allowed.includes(key));
+}