@hassangameryt/freeflow 0.7.2 → 0.8.0

package/pi-extension/dist/host/config.js

@@ -0,0 +1,374 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { resolveCognitiveRoutingState, supportsCognitiveRoutingModelRegistry } from "../cognitive-routing/config.js";
+import { sessionStage, stagedFor } from "./staging.js";
+import { resolveToolExecutionConfig, validateToolExecutionConfig } from "../tool-execution/config.js";
+import { resolveCompactionConfig, validateCompactionConfig } from "../compaction/config.js";
+import { cachedBranch } from "./branch.js";
+/**
+ * Freeflow configuration: the repository and personal config files, their layering, per-session core overrides, and
+ * the resulting capability state, with optional capabilities disabled inside subagents.
+ */
+/**
+ * Settings a session may override, as dotted config paths. "enabled" is Freeflow's master switch; the others switch a
+ * capability and are applied as a layer above the personal config.
+ */
+export const SESSION_OVERRIDE_KEYS = [
+  "enabled",
+  "cognitiveRouting.enabled",
+  "cognitiveRouting.projection",
+  "toolExecution.enabled",
+  "compaction.enabled",
+  "compaction.carry",
+];
+const SESSION_OVERRIDES_ENTRY = "freeflow-session-overrides";
+const SESSION_CORE_KEYS = new Set(SESSION_OVERRIDE_KEYS);
+let currentSessionOverrides = {};
+// pi-subagents stamps child system prompts with this tag before binding extensions.
+// Keeping detection at the prompt boundary avoids a process-global child flag.
+const SUBAGENT_AGENT_TAG = /<active_agent\s+name="[^"]+"\s*\/>/;
+const FREEFLOW_SUBAGENT_CAPABILITIES_DISABLED_MARKER = "<!-- freeflow-subagent-capabilities: disabled -->";
+const SUBAGENT_OPTIONAL_CAPABILITIES_MESSAGE = "Optional Freeflow capabilities are disabled for subagents.";
+function isSubagentContext(context) {
+  try {
+    const systemPrompt = context?.getSystemPrompt?.();
+    return (
+      typeof systemPrompt === "string" &&
+      (SUBAGENT_AGENT_TAG.test(systemPrompt) || systemPrompt.includes(FREEFLOW_SUBAGENT_CAPABILITIES_DISABLED_MARKER))
+    );
+  } catch {
+    return false;
+  }
+}
+function disableSubagentCapability(capability) {
+  return {
+    ...capability,
+    enabled: false,
+    effective: false,
+    blockingReason: { code: "disabled", message: SUBAGENT_OPTIONAL_CAPABILITIES_MESSAGE },
+  };
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function removedContextConfigError(value, filePath) {
+  const removedKeys = ["contextVirtualization", "conversationHistory"].filter((key) =>
+    Object.prototype.hasOwnProperty.call(value, key),
+  );
+  return removedKeys.length > 0
+    ? `Removed Freeflow context setting(s) in ${filePath}: ${removedKeys.join(", ")}. Delete those keys before using Freeflow.`
+    : null;
+}
+function validateCoreConfigFields(value) {
+  if (value.enabled !== undefined && typeof value.enabled !== "boolean") {
+    return "enabled must be a boolean";
+  }
+  return null;
+}
+function validateFreeflowConfigShape(value) {
+  if (!isRecord(value)) {
+    return "config must be a JSON object";
+  }
+  const removedContextError = removedContextConfigError(value, ".freeflow/config.json");
+  if (removedContextError) return removedContextError;
+  // outputRouter, observedRouting, and scriptTransform belong to retired features; they are accepted and ignored so
+  // existing configs keep loading.
+  const allowedKeys = new Set([
+    "enabled",
+    "outputRouter",
+    "observedRouting",
+    "scriptTransform",
+    "cognitiveRouting",
+    "toolExecution",
+    "compaction",
+  ]);
+  for (const key of Object.keys(value)) {
+    if (!allowedKeys.has(key)) {
+      return `unsupported top-level config key: ${key}`;
+    }
+  }
+  const coreError = validateCoreConfigFields(value);
+  if (coreError) return coreError;
+  for (const key of ["outputRouter", "observedRouting", "scriptTransform"]) {
+    if (value[key] !== undefined && !isRecord(value[key])) {
+      return `${key} must be an object`;
+    }
+  }
+  if (value.toolExecution !== undefined) {
+    const error = validateToolExecutionConfig(value.toolExecution);
+    if (error) return error;
+  }
+  if (value.compaction !== undefined) {
+    const error = validateCompactionConfig(value.compaction);
+    if (error) return error;
+  }
+  return null;
+}
+function validateFreeflowLocalConfigShape(value) {
+  if (!isRecord(value)) {
+    return "local config must be a JSON object";
+  }
+  const removedContextError = removedContextConfigError(value, ".freeflow/local.json");
+  if (removedContextError) return removedContextError;
+  // processing belongs to a retired feature; it is accepted and ignored so existing local configs keep loading.
+  const allowedKeys = new Set(["enabled", "processing", "cognitiveRouting", "toolExecution", "compaction"]);
+  for (const key of Object.keys(value)) {
+    if (!allowedKeys.has(key)) {
+      return `unsupported top-level local config key: ${key}`;
+    }
+  }
+  const coreError = validateCoreConfigFields(value);
+  if (coreError) return coreError;
+  if (value.toolExecution !== undefined) {
+    const error = validateToolExecutionConfig(value.toolExecution);
+    if (error) return error;
+  }
+  if (value.compaction !== undefined) return validateCompactionConfig(value.compaction);
+  return null;
+}
+async function readConfigFileState(path, validate) {
+  try {
+    const raw = await readFile(path, "utf8");
+    const parsed = JSON.parse(raw);
+    const validationError = validate(parsed);
+    if (validationError) {
+      return {
+        path,
+        exists: true,
+        valid: false,
+        parsed: {},
+        parseError: validationError,
+      };
+    }
+    return { path, exists: true, valid: true, parsed, parseError: null };
+  } catch (error) {
+    const code = error && typeof error === "object" ? error.code : undefined;
+    if (code === "ENOENT") {
+      return {
+        path,
+        exists: false,
+        valid: false,
+        parsed: {},
+        parseError: null,
+      };
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      path,
+      exists: true,
+      valid: false,
+      parsed: {},
+      parseError: message,
+    };
+  }
+}
+function readFreeflowConfigState(cwd) {
+  return readConfigFileState(join(cwd, ".freeflow/config.json"), validateFreeflowConfigShape);
+}
+function readFreeflowLocalConfigState(cwd) {
+  return readConfigFileState(join(cwd, ".freeflow/local.json"), validateFreeflowLocalConfigShape);
+}
+export async function readFreeflowConfig(cwd) {
+  const state = await readFreeflowConfigState(cwd);
+  return state.valid ? state.parsed : {};
+}
+export async function readFreeflowLocalConfig(cwd) {
+  const state = await readFreeflowLocalConfigState(cwd);
+  return state.valid ? state.parsed : {};
+}
+function resolveLayeredValue(repository, local, key, fallback) {
+  if (Object.hasOwn(local, key)) {
+    return { value: local[key], source: "local" };
+  }
+  if (Object.hasOwn(repository, key)) {
+    return { value: repository[key], source: "repository" };
+  }
+  return { value: fallback, source: "builtin" };
+}
+function resolveCoreConfig(repository, local) {
+  const enabled = resolveLayeredValue(repository, local, "enabled", true);
+  return {
+    config: { enabled: enabled.value },
+    sources: { enabled: enabled.source },
+  };
+}
+function normalizeSessionOverrides(value) {
+  if (!isRecord(value)) return {};
+  const overrides = {};
+  for (const key of SESSION_CORE_KEYS) {
+    if (typeof value[key] === "boolean") {
+      overrides[key] = value[key];
+    }
+  }
+  return overrides;
+}
+/** The capability overrides of this session as a config layer, e.g. { compaction: { carry: false } }. */
+function sessionConfigLayer(overrides) {
+  const layer = {};
+  for (const [key, value] of Object.entries(overrides)) {
+    const [section, field] = key.split(".");
+    if (!field || typeof value !== "boolean") continue;
+    layer[section] = { ...(layer[section] ?? {}), [field]: value };
+  }
+  return layer;
+}
+function withSessionLayer(local, session) {
+  const merged = { ...local };
+  for (const [section, fields] of Object.entries(session))
+    merged[section] = { ...(isRecord(local[section]) ? local[section] : {}), ...fields };
+  return merged;
+}
+function resolveSessionCoreConfig(layers) {
+  const configured = layers.coreConfig;
+  const sources = layers.sources;
+  const enabled = currentSessionOverrides.enabled;
+  return {
+    config: { enabled: typeof enabled === "boolean" ? enabled : configured.enabled },
+    sources: { enabled: typeof enabled === "boolean" ? "session" : sources.enabled },
+  };
+}
+export async function readFreeflowConfigLayers(cwd) {
+  const [repository, local] = await Promise.all([readFreeflowConfigState(cwd), readFreeflowLocalConfigState(cwd)]);
+  const repositoryConfig = repository.valid ? repository.parsed : {};
+  const localConfig = local.valid ? local.parsed : {};
+  const core = resolveCoreConfig(repositoryConfig, localConfig);
+  const localValid = !local.exists || local.valid;
+  const configured = repository.valid && localValid;
+  let blockingState = null;
+  if (!repository.valid) {
+    blockingState = repository;
+  } else if (local.exists && !local.valid) {
+    blockingState = local;
+  }
+  return {
+    configured,
+    repositoryConfigured: repository.valid,
+    repository,
+    local,
+    coreConfig: core.config,
+    sources: core.sources,
+    blockingConfigPath: blockingState?.path ?? null,
+    parseError: blockingState?.parseError ?? null,
+  };
+}
+export async function readCapabilityState(cwd, host = undefined) {
+  const layers = await readFreeflowConfigLayers(cwd);
+  const effectiveCore = resolveSessionCoreConfig(layers);
+  const enabled = layers.configured && effectiveCore.config.enabled;
+  const subagentContext = isSubagentContext(host);
+  const hostSupportsCognitiveRouting = !subagentContext && supportsCognitiveRoutingModelRegistry(host);
+  const sessionLayer = sessionConfigLayer(currentSessionOverrides);
+  const configuredCognitiveRouting = await resolveCognitiveRoutingState(
+    layers.repository.parsed,
+    layers.local.parsed,
+    hostSupportsCognitiveRouting ? host : undefined,
+    sessionLayer,
+  );
+  const disabledReason = enabled ? undefined : { code: "disabled", message: "Freeflow is disabled" };
+  const cognitiveRouting = enabled
+    ? configuredCognitiveRouting
+    : {
+        ...configuredCognitiveRouting,
+        enabled: false,
+        effective: false,
+        blockingReason: disabledReason,
+      };
+  const repositoryConfig = layers.repository.valid ? layers.repository.parsed : {};
+  const localConfig = layers.local.valid ? layers.local.parsed : {};
+  const sessionLocalConfig = withSessionLayer(localConfig, sessionLayer);
+  const toolExecution = resolveToolExecutionConfig(repositoryConfig, sessionLocalConfig, enabled);
+  const compaction = resolveCompactionConfig(repositoryConfig, sessionLocalConfig, enabled);
+  const capabilityState = {
+    configured: layers.configured,
+    repositoryConfigured: layers.repositoryConfigured,
+    configExists: layers.repository.exists,
+    configValid: layers.configured,
+    configPath: layers.blockingConfigPath ?? layers.repository.path,
+    parseError: layers.parseError,
+    localConfigExists: layers.local.exists,
+    localConfigValid: !layers.local.exists || layers.local.valid,
+    localConfigPath: layers.local.path,
+    localConfigParseError: layers.local.parseError,
+    configuredCoreConfig: layers.coreConfig,
+    configuredSources: layers.sources,
+    sessionOverrides: { ...currentSessionOverrides },
+    configSources: effectiveCore.sources,
+    enabled,
+    hostSupportsCognitiveRouting,
+    cognitiveRouting,
+    toolExecution,
+    compaction,
+  };
+  if (!subagentContext) return capabilityState;
+  return {
+    ...capabilityState,
+    cognitiveRouting: disableSubagentCapability(capabilityState.cognitiveRouting),
+    toolExecution: disableSubagentCapability(capabilityState.toolExecution),
+    compaction: disableSubagentCapability(capabilityState.compaction),
+  };
+}
+function recordedSessionOverrides(sessionManager) {
+  let recorded = {};
+  for (const entry of sessionManager?.getBranch ? cachedBranch(sessionManager) : (sessionManager?.getEntries?.() ?? []))
+    if (entry.type === "custom" && entry.customType === SESSION_OVERRIDES_ENTRY)
+      recorded = normalizeSessionOverrides(entry.data?.overrides);
+  return recorded;
+}
+export function restoreSessionOverrides(ctx) {
+  const staged = stagedFor(ctx.sessionManager)?.overrides;
+  currentSessionOverrides = normalizeSessionOverrides(staged ?? recordedSessionOverrides(ctx.sessionManager));
+}
+/** Session overrides change nothing until the next prompt, so they are staged and written then. */
+function recordSessionOverrides(ctx, pi) {
+  const stage = sessionStage(ctx?.sessionManager);
+  if (stage) stage.overrides = { ...currentSessionOverrides };
+  else pi?.appendEntry?.(SESSION_OVERRIDES_ENTRY, { overrides: { ...currentSessionOverrides } });
+}
+/** Write staged session overrides at the start of a prompt, unless they equal what the session recorded. */
+export function writeStagedSessionOverrides(overrides, pi, sessionManager) {
+  if (!overrides) return;
+  const next = normalizeSessionOverrides(overrides);
+  if (JSON.stringify(next) === JSON.stringify(recordedSessionOverrides(sessionManager))) return;
+  pi?.appendEntry?.(SESSION_OVERRIDES_ENTRY, { overrides: { ...next } });
+}
+export async function setSessionCoreOverride(key, value, ctx, pi) {
+  if (!SESSION_CORE_KEYS.has(key)) {
+    throw new Error(`Invalid Freeflow session override: ${String(key)}`);
+  }
+  if (value !== null && typeof value !== "boolean") {
+    throw new Error(`Invalid Freeflow session override value for ${key}: ${String(value)}`);
+  }
+  const hasOverride = Object.hasOwn(currentSessionOverrides, key);
+  if ((value === null && !hasOverride) || (value !== null && hasOverride && currentSessionOverrides[key] === value)) {
+    return { changed: false, sessionOverrides: { ...currentSessionOverrides } };
+  }
+  const next = { ...currentSessionOverrides };
+  if (value === null) {
+    delete next[key];
+  } else {
+    next[key] = value;
+  }
+  currentSessionOverrides = next;
+  recordSessionOverrides(ctx, pi);
+  return {
+    changed: true,
+    // Every session override switches Freeflow or a capability, which changes tools and guidance: reload.
+    reloadRequired: true,
+    sessionOverrides: { ...currentSessionOverrides },
+    capabilityState: await readCapabilityState(ctx.cwd, ctx),
+  };
+}
+export async function resetSessionOverrides(ctx, pi) {
+  const hadCoreOverrides = Object.keys(currentSessionOverrides).length > 0;
+  const reloadRequired = hadCoreOverrides;
+  if (hadCoreOverrides) {
+    currentSessionOverrides = {};
+    recordSessionOverrides(ctx, pi);
+  }
+  return {
+    changed: hadCoreOverrides,
+    reloadRequired,
+    sessionOverrides: { ...currentSessionOverrides },
+    capabilityState: await readCapabilityState(ctx.cwd, ctx),
+  };
+}

package/pi-extension/dist/host/projection-tags.js

@@ -0,0 +1,60 @@
+const projectedEntryIds = new WeakMap();
+// Messages that came from an aligned projection; anything else in the request was generated after it.
+const projectedMessages = new WeakSet();
+// Projected messages whose body a host edit replaced; only these still need content association.
+const editedMessages = new WeakSet();
+/** The unedited native entry behind a request message, when Pi's projection established it. */
+export function projectedEntryId(message) {
+  return message && typeof message === "object" ? projectedEntryIds.get(message) : undefined;
+}
+export function tagProjectedMessages(messages, projection, branch) {
+  if (!projection) return;
+  let count = 0;
+  for (const entry of projection.entries) count += entry.messages.length;
+  if (count !== messages.length) return;
+  let index = 0;
+  for (const entry of projection.entries)
+    for (const projected of entry.messages) if (projected?.role !== messages[index++]?.role) return;
+  // Host edits change the visible body, so their targets keep exact content association.
+  const edited = new Set();
+  for (const entry of branch) if (entry.type === "context_edit") edited.add(entry.targetId);
+  index = 0;
+  for (const entry of projection.entries) {
+    const source = entry.sourceEntry;
+    for (const _projected of entry.messages) {
+      const message = messages[index++];
+      if (!message || typeof message !== "object") continue;
+      projectedMessages.add(message);
+      if (edited.has(source.id)) editedMessages.add(message);
+      if (
+        entry.messages.length === 1 &&
+        (source.type === "message" || source.type === "custom_message") &&
+        !edited.has(source.id)
+      )
+        projectedEntryIds.set(message, source.id);
+    }
+  }
+}
+// Messages Freeflow renders from an entry (routing's views): the entry and the rendering variant, so a consumer can
+// fingerprint each rendering once. Kept apart from projectedEntryIds, which names only unedited native messages.
+const derivedIdentities = new WeakMap();
+/** Mark a message rendered from a native entry with a stable identity: `<entry id>#<variant>` or another unique key. */
+export function tagDerived(message, identity) {
+  derivedIdentities.set(message, identity);
+}
+/**
+ * A stable identity for a request message whose content never changes under that identity: the unedited native entry
+ * behind it, or the identity of a rendering. Undefined for generated or host-edited messages.
+ */
+export function occurrenceIdentity(message) {
+  if (!message || typeof message !== "object") return undefined;
+  return derivedIdentities.get(message) ?? projectedEntryIds.get(message);
+}
+/** Whether a request message came from an aligned Pi projection. */
+export function isProjected(message) {
+  return !!message && typeof message === "object" && projectedMessages.has(message);
+}
+/** Whether a host edit replaced the body of a projected request message. */
+export function isHostEdited(message) {
+  return !!message && typeof message === "object" && editedMessages.has(message);
+}

package/pi-extension/dist/host/prompts.js

@@ -0,0 +1,82 @@
+import { readFile } from "node:fs/promises";
+/**
+ * Freeflow's prompt files and the fixed system section built from them. The section never changes with feature state
+ * so it stays cached; the Runtime State tells the model what is active.
+ */
+let runtimeContextCache = null;
+export function isPromptAvailable(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+export function hasUsableMandatoryPrompts(freeflowContext) {
+  return (
+    isPromptAvailable(freeflowContext?.corePrompt) && isPromptAvailable(freeflowContext?.interactionContractPrompt)
+  );
+}
+async function readPromptFile(url) {
+  try {
+    const prompt = await readFile(url, "utf8");
+    return isPromptAvailable(prompt) ? prompt.trim() : null;
+  } catch {
+    return null;
+  }
+}
+async function loadRuntimeContext(capabilityState = undefined) {
+  const freeflowEnabled = capabilityState?.enabled === true;
+  const cognitiveRoutingEnabled = capabilityState?.cognitiveRouting?.effective === true;
+  const [corePrompt, interactionContractPrompt, workingMethodPrompt, cognitiveRoutingPrompt, toolExecutionPrompt] =
+    await Promise.all([
+      freeflowEnabled
+        ? readPromptFile(new URL("../../../runtime/prompts/core.md", import.meta.url))
+        : Promise.resolve(null),
+      freeflowEnabled
+        ? readPromptFile(new URL("../../../runtime/prompts/interaction-contract.md", import.meta.url))
+        : Promise.resolve(null),
+      freeflowEnabled
+        ? readPromptFile(new URL("../../../runtime/prompts/working-method.md", import.meta.url))
+        : Promise.resolve(null),
+      cognitiveRoutingEnabled
+        ? readPromptFile(new URL("../../../runtime/prompts/cognitive-routing.md", import.meta.url))
+        : Promise.resolve(null),
+      capabilityState?.toolExecution?.effective === true
+        ? readPromptFile(new URL("../../../runtime/prompts/tool-execution.md", import.meta.url))
+        : Promise.resolve(null),
+    ]);
+  return { corePrompt, interactionContractPrompt, workingMethodPrompt, cognitiveRoutingPrompt, toolExecutionPrompt };
+}
+function runtimeContextCacheSatisfies(capabilityState) {
+  if (!runtimeContextCache) return false;
+  const expected = {
+    corePrompt: capabilityState?.enabled === true,
+    interactionContractPrompt: capabilityState?.enabled === true,
+    cognitiveRoutingPrompt: capabilityState?.cognitiveRouting?.effective === true,
+  };
+  return Object.entries(expected).every(([key, required]) => !required || isPromptAvailable(runtimeContextCache[key]));
+}
+export async function refreshRuntimeContext(capabilityState = undefined) {
+  runtimeContextCache = await loadRuntimeContext(capabilityState);
+  return runtimeContextCache;
+}
+export async function getRuntimeContext(capabilityState = undefined) {
+  if (runtimeContextCacheSatisfies(capabilityState)) {
+    return runtimeContextCache;
+  }
+  return refreshRuntimeContext(capabilityState);
+}
+export function stableRuntimeContext(context) {
+  const sections = [
+    ["Freeflow core", context?.corePrompt],
+    ["Freeflow core", context?.interactionContractPrompt],
+    ["Working Method", context?.workingMethodPrompt],
+    ["Cognitive Routing", context?.cognitiveRoutingPrompt],
+  ];
+  return [
+    "# Freeflow availability contract",
+    "Freeflow keeps a fixed reference catalog of its instructions, skills, and tools to preserve prompt caching. Presence in this catalog does not mean a feature is active or an operation is permitted.",
+    "Apply the following guidance and Freeflow skills only when the latest extension-generated Freeflow Runtime State marks the corresponding feature active. When Freeflow is inactive, unavailable, or not configured, its core and capability guidance is dormant; do not bootstrap or follow it merely because it is listed. Explicit user instructions retain their normal authority.",
+    "For Cognitive Routing, follow the latest control/profile/responsibility snapshots on this branch. Earlier snapshots and notices are historical; they grant no current permission. Tool permissions are checked by the runtime, even though all definitions remain visible. Never call a disabled operation.",
+    "Messages that start with `[Freeflow notice, not from the user]` come from Freeflow, not the user. They report facts and harness steps; they are not the user's instructions.",
+    ...sections
+      .filter(([, text]) => isPromptAvailable(text))
+      .map(([feature, text]) => `## Reference guidance: ${feature}\n\n${text.trim()}`),
+  ].join("\n\n");
+}

package/pi-extension/dist/{session-sources → host}/read-only-session.js

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
-import { open, stat } from "node:fs/promises";
+import { statSync } from "node:fs";
+import { lstat, open, stat } from "node:fs/promises";
 import { TextDecoder } from "node:util";
 export class ReadOnlySessionError extends Error {
   code;
@@ -50,7 +51,10 @@ export function parseReadOnlySessionText(text) {
   const seen = new Set();
   return lines.map((line, i) => decodeEntry(line, i + 1, seen));
 }
+/** Whole-file snapshots read so far; tests check that a verified startup reads none. */
+export const readOnlySessionCounters = { snapshots: 0 };
 export async function readOnlySessionSnapshot(path, options = {}) {
+  readOnlySessionCounters.snapshots++;
   const limits = { ...SESSION_READ_LIMITS, ...options };
   if (Object.values(limits).some((n) => !Number.isSafeInteger(n) || n <= 0))
     throw new ReadOnlySessionError("invalid_limit", "Invalid snapshot limit.");
@@ -146,3 +150,110 @@ export function activeReadOnlySessionBranch(snapshot, leafId) {
   }
   return path.reverse();
 }
+// Byte offset and entry count up to which a session file is known to equal Pi's in-memory entries.
+const verified = new Map();
+/** Pi just parsed this file into memory, so its current bytes are the verified prefix. */
+export function trustLoadedSession(reader) {
+  const path = reader.getSessionFile?.();
+  if (!path) return;
+  try {
+    verified.set(path, { size: statSync(path).size, count: reader.getEntries().length });
+  } catch {
+    verified.delete(path);
+  }
+}
+/**
+ * At `session_start`, trust the file only when Pi just parsed it. A reload keeps Pi's session in memory without
+ * re-reading the file, so it establishes nothing: after a failed write, memory could hold an entry the file lacks.
+ * The previous trust point, or a full check, still applies after a reload.
+ */
+export function trustStartedSession(reason, reader) {
+  if (reason !== "reload") trustLoadedSession(reader);
+}
+async function tailMatches(path, reader) {
+  const point = verified.get(path);
+  if (!point) return false;
+  const entries = reader.getEntries();
+  let file;
+  try {
+    file = await open(path, "r");
+    const { size } = await file.stat();
+    if (size < point.size || entries.length < point.count) return false;
+    const buffer = Buffer.alloc(size - point.size);
+    const { bytesRead } = await file.read(buffer, 0, buffer.length, point.size);
+    if (bytesRead !== buffer.length) return false;
+    const lines = new TextDecoder("utf-8", { fatal: true }).decode(buffer).split("\n");
+    if (lines.pop() !== "") return false;
+    const appended = entries.slice(point.count);
+    // Pi appends each entry as its JSON serialization, in memory order.
+    if (lines.length !== appended.length || lines.some((line, i) => line !== JSON.stringify(appended[i]))) return false;
+    verified.set(path, { size, count: entries.length });
+    return true;
+  } catch {
+    return false;
+  } finally {
+    await file?.close();
+  }
+}
+/**
+ * Whether every entry Pi holds is persisted, judged only by the bytes appended since the trust point: true when the
+ * file grew by exactly those entries. False when there is no trust point or anything differs; callers then fall back
+ * to a full snapshot.
+ */
+export async function persistedTailMatches(reader) {
+  const path = reader.getSessionFile?.();
+  return !!path && (await tailMatches(path, reader));
+}
+/** Verify one newly appended native anchor without re-reading the historical session. */
+export async function persistedLastEntryMatches(path, entry) {
+  if (!path) return false;
+  let file;
+  try {
+    const expected = Buffer.from(`${JSON.stringify(entry)}\n`, "utf8");
+    if (!expected.length || expected.length > 1024 * 1024) return false;
+    const named = await lstat(path, { bigint: true });
+    if (!named.isFile() || named.isSymbolicLink() || named.size < BigInt(expected.length)) return false;
+    file = await open(path, "r");
+    const before = await file.stat({ bigint: true });
+    if (before.size > BigInt(Number.MAX_SAFE_INTEGER)) return false;
+    const actual = Buffer.alloc(expected.length);
+    let offset = 0;
+    while (offset < actual.length) {
+      const read = await file.read(
+        actual,
+        offset,
+        actual.length - offset,
+        Number(before.size) - actual.length + offset,
+      );
+      if (!read.bytesRead) return false;
+      offset += read.bytesRead;
+    }
+    const after = await file.stat({ bigint: true });
+    const current = await lstat(path, { bigint: true });
+    const signature = (value) => [value.dev, value.ino, value.size, value.mtimeNs, value.ctimeNs].join(":");
+    return (
+      before.isFile() &&
+      signature(named) === signature(before) &&
+      signature(before) === signature(after) &&
+      signature(after) === signature(current) &&
+      actual.equals(expected)
+    );
+  } catch {
+    return false;
+  } finally {
+    await file?.close();
+  }
+}
+/** Whether the persisted session holds exactly this branch: tail-only after a trust point, else a full comparison. */
+export async function persistedBranchMatches(reader, leaf, branch) {
+  const path = reader.getSessionFile?.();
+  if (!path) return false;
+  if (await tailMatches(path, reader)) return true;
+  const snapshot = await readOnlySessionSnapshot(path);
+  const matches =
+    snapshot.sessionId === reader.getSessionId() &&
+    JSON.stringify(activeReadOnlySessionBranch(snapshot, leaf)) === JSON.stringify(branch);
+  if (matches) trustLoadedSession(reader);
+  else verified.delete(path);
+  return matches;
+}