@hassangameryt/freeflow 0.7.1 → 0.7.3

package/pi-extension/dist/runtime/runtime-context.js

@@ -1,8 +1,8 @@
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { resolveCognitiveRoutingState } from "../cognitive-routing/runtime.js";
-import { supportsCognitiveRoutingModelRegistry } from "../cognitive-routing/host.js";
+import { resolveCognitiveRoutingState } from "../cognitive-routing-v2/config.js";
+import { supportsCognitiveRoutingModelRegistry } from "../cognitive-routing-v2/config.js";
 export const WORKFLOW_COMMANDS = [
   { command: "discuss", skill: "discuss" },
   { command: "action-selection", skill: "action-selection" },
@@ -43,7 +43,6 @@ export const FREEFLOW_MODEL_SKILL_NAMES = [
   "setup-freeflow",
   "launch-work",
   "simplify-code",
-  "tdd",
   "track-work",
   "verify-work",
   "workflow",
@@ -51,6 +50,12 @@ export const FREEFLOW_MODEL_SKILL_NAMES = [
   "write-skill",
   "write-spec",
 ];
+export const STABLE_FREEFLOW_SURFACE = Object.freeze({
+  enabled: true,
+  cognitiveRouting: { effective: true },
+  contextVirtualization: { effective: true },
+  conversationHistory: { effective: true },
+});
 export const FREEFLOW_CAPABILITY_SKILL_NAMES = ["cognitive-routing", "context-virtualization", "conversation-history"];
 export function freeflowSkillPath(skillName) {
   return fileURLToPath(new URL(`../../../skills/${skillName}/SKILL.md`, import.meta.url));
@@ -74,7 +79,6 @@ export function freeflowModelSkillPaths(capabilityState = undefined) {
 }
 const SESSION_OVERRIDES_ENTRY = "freeflow-session-overrides";
 const SESSION_CORE_KEYS = new Set(["enabled", "contextVirtualization", "conversationHistory"]);
-export const COGNITIVE_ROUTING_SWITCH_TOOL_NAME = "freeflow_switch_profile";
 export const FREEFLOW_RUNTIME_STATE_MESSAGE_TYPE = "freeflow-runtime-state";
 export const COGNITIVE_ROUTING_RUNTIME_STATE_MESSAGE_TYPE = "freeflow-cognitive-routing-runtime-state";
 export const WORKFLOW_BOOTSTRAP_MESSAGE_TYPE = "freeflow-workflow-bootstrap";
@@ -85,6 +89,30 @@ let currentSessionOverrides = {};
 export function isPromptAvailable(value) {
   return typeof value === "string" && value.trim().length > 0;
 }
+// pi-subagents stamps child system prompts with this tag before binding extensions.
+// Keeping detection at the prompt boundary avoids a process-global child flag.
+export const SUBAGENT_AGENT_TAG = /<active_agent\s+name="[^"]+"\s*\/>/;
+export const FREEFLOW_SUBAGENT_CAPABILITIES_DISABLED_MARKER = "<!-- freeflow-subagent-capabilities: disabled -->";
+const SUBAGENT_OPTIONAL_CAPABILITIES_MESSAGE = "Optional Freeflow capabilities are disabled for subagents.";
+export 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 },
+  };
+}
 export function hasUsableMandatoryPrompts(freeflowContext) {
   return (
     isPromptAvailable(freeflowContext?.corePrompt) && isPromptAvailable(freeflowContext?.interactionContractPrompt)
@@ -380,7 +408,8 @@ export async function readCapabilityState(cwd, host = undefined, extensionHost =
   const enabled = layers.configured && effectiveCore.config.enabled;
   const contextVirtualizationConfigEnabled = effectiveCore.config.contextVirtualization;
   const conversationHistoryConfigEnabled = effectiveCore.config.conversationHistory;
-  const hostSupportsCognitiveRouting = supportsCognitiveRoutingModelRegistry(host);
+  const subagentContext = isSubagentContext(host);
+  const hostSupportsCognitiveRouting = !subagentContext && supportsCognitiveRoutingModelRegistry(host);
   const configuredCognitiveRouting = await resolveCognitiveRoutingState(
     layers.repository.parsed,
     layers.local.parsed,
@@ -400,7 +429,7 @@ export async function readCapabilityState(cwd, host = undefined, extensionHost =
         effective: false,
         blockingReason: disabledReason,
       };
-  return {
+  const capabilityState = {
     configured: layers.configured,
     repositoryConfigured: layers.repositoryConfigured,
     configExists: layers.repository.exists,
@@ -421,6 +450,13 @@ export async function readCapabilityState(cwd, host = undefined, extensionHost =
     hostSupportsCognitiveRouting,
     cognitiveRouting,
   };
+  if (!subagentContext) return capabilityState;
+  return {
+    ...capabilityState,
+    contextVirtualization: disableSubagentCapability(capabilityState.contextVirtualization),
+    conversationHistory: disableSubagentCapability(capabilityState.conversationHistory),
+    cognitiveRouting: disableSubagentCapability(capabilityState.cognitiveRouting),
+  };
 }
 export const readRuntimeState = readCapabilityState;
 export function restoreSessionOverrides(ctx) {
@@ -468,11 +504,7 @@ export function setFreeflowStatus(
     active.push(`cognitive blocked · ${cognitiveRoutingRuntime?.runtimeReason ?? "runtime_blocked"}`);
   } else if (cognitiveRoutingActive) {
     const profile = cognitiveRoutingRuntime.activeProfile;
-    const control =
-      cognitiveRoutingRuntime.controlMode === "manual-standard" ||
-      cognitiveRoutingRuntime.controlMode === "manual-reasoning"
-        ? "manual hold"
-        : "automatic";
+    const control = String(cognitiveRoutingRuntime.controlMode).startsWith("manual-") ? "manual hold" : "automatic";
     active.push(`${profile} · ${control}`);
   } else if (cognitiveRouting?.enabled === true) {
     if (cognitiveRouting.blockingReason?.code === "runtime_disabled") {
@@ -485,8 +517,8 @@ export function setFreeflowStatus(
     ) {
       const startupProfile =
         cognitiveRouting.sessionStart?.control === "manual"
-          ? (cognitiveRouting.sessionStart.profile ?? "reasoning")
-          : "reasoning";
+          ? (cognitiveRouting.sessionStart.profile ?? "coordinator")
+          : "coordinator";
       active.push(`${startupProfile} · pending`);
     } else {
       const reason =
@@ -507,12 +539,12 @@ export function skillPrompt(skill, args) {
 }
 function publicCognitiveRoutingControl(controlMode) {
   if (controlMode === "automatic") return "automatic";
-  if (controlMode === "manual-standard" || controlMode === "manual-reasoning") return "manual";
+  if (["manual-helper", "manual-executor", "manual-coordinator"].includes(controlMode)) return "manual";
   return "unavailable";
 }
 function publicCognitiveRoutingProfile(activeProfile, effective) {
   if (effective !== true) return "unavailable";
-  return activeProfile === "standard" || activeProfile === "reasoning" ? activeProfile : "unavailable";
+  return ["helper", "executor", "coordinator"].includes(activeProfile) ? activeProfile : "unavailable";
 }
 function publicCapabilityStatus(capability) {
   if (capability?.effective === true) return "active";
@@ -525,10 +557,20 @@ function publicCognitiveRoutingStatus(capability, runtime) {
   if (runtime?.runtimeStatus === "inactive") return "inactive";
   return publicCapabilityStatus(capability);
 }
+function publicCognitiveRoutingProjectionMode(capability, runtime, projectionFailure) {
+  if (capability?.projection !== true) return "disabled";
+  if (capability?.effective !== true) return "unavailable";
+  if (String(runtime?.controlMode).startsWith("manual-")) return "manual-bypass";
+  if (projectionFailure) return "blocked";
+  if (runtime?.runtimeStatus === "inactive" || runtime?.runtimeStatus === "blocked") return "unavailable";
+  if (runtime?.effective === true && runtime.controlMode === "automatic") return "enabled";
+  return "pending";
+}
 export function freeflowRuntimeStateMessage(
   capabilityState,
   cognitiveRoutingRuntime = undefined,
   freeflowContext = undefined,
+  options = {},
 ) {
   const cognitiveRoutingEffective = capabilityState?.cognitiveRouting?.effective === true;
   const profile = publicCognitiveRoutingProfile(
@@ -537,6 +579,11 @@ export function freeflowRuntimeStateMessage(
   );
   const control =
     profile === "unavailable" ? "unavailable" : publicCognitiveRoutingControl(cognitiveRoutingRuntime?.controlMode);
+  const projectionMode = publicCognitiveRoutingProjectionMode(
+    capabilityState?.cognitiveRouting,
+    cognitiveRoutingRuntime,
+    options.projectionFailure,
+  );
   const mandatoryPromptAvailable = capabilityState?.enabled !== true || hasUsableMandatoryPrompts(freeflowContext);
   const freeflowStatus = capabilityState?.configured
     ? capabilityState.enabled
@@ -565,6 +612,8 @@ export function freeflowRuntimeStateMessage(
       "Cognitive Routing:",
       `- Control: \`${control}\``,
       `- Profile: \`${profile}\``,
+      `- Delegation: \`${capabilityState?.cognitiveRouting?.delegation ?? "executor"}\``,
+      `- Projection: \`${projectionMode}\``,
     ].join("\n"),
     display: false,
     details: { source: "provider-request-runtime-state" },
@@ -596,7 +645,9 @@ export function withFreeflowRuntimeState(
   options = {},
 ) {
   const source = Array.isArray(messages) ? messages : [];
-  const runtimeState = freeflowRuntimeStateMessage(capabilityState, cognitiveRoutingRuntime, freeflowContext);
+  const runtimeState = freeflowRuntimeStateMessage(capabilityState, cognitiveRoutingRuntime, freeflowContext, {
+    projectionFailure: options.projectionFailure,
+  });
   const runtimeStateMessages = source.filter(
     (message) =>
       message?.customType === FREEFLOW_RUNTIME_STATE_MESSAGE_TYPE ||
@@ -614,6 +665,24 @@ export function withFreeflowRuntimeState(
   if (unchanged) return source;
   return insertRuntimeStateBeforeLatestUser(withoutRuntimeState, runtimeState);
 }
+export function stableRuntimeContext(context) {
+  const sections = [
+    ["Freeflow core", context?.corePrompt],
+    ["Freeflow core", context?.interactionContractPrompt],
+    ["Cognitive Routing", context?.cognitiveRoutingPrompt],
+    ["Context Virtualization", context?.contextVirtualizationPrompt],
+    ["Conversation History", context?.conversationHistoryPrompt],
+  ];
+  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.",
+    ...sections
+      .filter(([, text]) => isPromptAvailable(text))
+      .map(([feature, text]) => `## Reference guidance: ${feature}\n\n${text.trim()}`),
+  ].join("\n\n");
+}
 export function runtimeContext(freeflowContext, capabilityState) {
   if (
     capabilityState?.configured !== true ||

package/pi-extension/dist/session-sources/events.js

@@ -0,0 +1,217 @@
+import { randomUUID } from "node:crypto";
+import { activeReadOnlySessionBranch, readOnlySessionSnapshot, ReadOnlySessionError } from "./read-only-session.js";
+import {
+  ROUTING_ENTRY,
+  RoutingError,
+  canonical,
+  eventKey,
+  eventValue,
+  requireCondition as check,
+} from "../cognitive-routing-v2/types.js";
+import { parseRoutingEvent, reduce, replay } from "../cognitive-routing-v2/state.js";
+export class EventStore {
+  pi;
+  reader;
+  observed = new Map();
+  attempted = new Map();
+  fault;
+  ready = false;
+  cachedEntries = [];
+  cachedState = replay([]);
+  constructor(pi, reader) {
+    this.pi = pi;
+    this.reader = reader;
+  }
+  get blocked() {
+    return this.fault ?? (!this.ready ? "acknowledgment_unclassified" : undefined);
+  }
+  state() {
+    const entries = this.reader.getBranch();
+    const prefix =
+      this.cachedEntries.length <= entries.length && this.cachedEntries.every((entry, i) => entry === entries[i]);
+    if (!prefix) {
+      this.cachedState = replay(entries);
+    } else {
+      let state = this.cachedState;
+      for (const entry of entries.slice(this.cachedEntries.length))
+        if (entry.type === "custom" && entry.customType === ROUTING_ENTRY)
+          state = reduce(state, parseRoutingEvent(entry.data));
+      this.cachedState = state;
+    }
+    this.cachedEntries = [...entries];
+    return this.cachedState;
+  }
+  block(reason) {
+    this.fault = reason;
+    this.ready = false;
+  }
+  make(data, operationId = randomUUID(), stepId = data.type) {
+    return parseRoutingEvent({
+      version: 2,
+      eventId: randomUUID(),
+      operationId,
+      stepId,
+      recordedSessionId: this.reader.getSessionId(),
+      data,
+    });
+  }
+  async reconcile() {
+    const acknowledged = this.ready && !this.fault;
+    this.ready = false;
+    const branch = this.reader.getBranch();
+    const live = branch.filter((e) => e.type === "custom" && e.customType === ROUTING_ENTRY);
+    try {
+      const ids = new Set();
+      let parent = null;
+      for (const entry of branch) {
+        check(
+          typeof entry.id === "string" && !ids.has(entry.id) && entry.parentId === parent,
+          "invalid_native_ancestry",
+        );
+        ids.add(entry.id);
+        parent = entry.id;
+      }
+      check(parent === this.reader.getLeafId(), "invalid_native_ancestry");
+      if (
+        acknowledged &&
+        live.every((entry) => {
+          const event = parseRoutingEvent(entry.data);
+          const receipt = this.observed.get(eventKey(event));
+          return (
+            receipt?.entryId === entry.id && receipt.eventId === event.eventId && receipt.value === eventValue(event)
+          );
+        })
+      ) {
+        this.ready = true;
+        return;
+      }
+      if (!live.length && !this.attempted.size) {
+        this.observed.clear();
+        this.fault = undefined;
+        this.ready = true;
+        return;
+      }
+      // Pi defers creating a new session file until its first assistant message.
+      // Before that flush boundary, the complete in-memory native session is the
+      // only available source; uncertain appends still require persisted readback.
+      const preFlush =
+        !this.attempted.size &&
+        !this.reader.getEntries().some((entry) => entry.type === "message" && entry.message?.role === "assistant");
+      if (preFlush) {
+        replay(branch);
+        const known = new Map();
+        for (const entry of branch) {
+          if (entry.type === "custom" && entry.customType === ROUTING_ENTRY) {
+            const event = parseRoutingEvent(entry.data);
+            known.set(eventKey(event), { value: eventValue(event), eventId: event.eventId, entryId: entry.id });
+          }
+        }
+        this.observed = known;
+        this.fault = undefined;
+        this.ready = true;
+        this.cachedEntries = [];
+        this.cachedState = replay([]);
+        return;
+      }
+      const path = this.reader.getSessionFile();
+      check(path, "persisted_snapshot_unavailable", "Existing or uncertain routing state needs a persisted snapshot.");
+      const snapshot = await readOnlySessionSnapshot(path);
+      check(snapshot.sessionId === this.reader.getSessionId(), "session_identity_changed");
+      const persistedBranch = activeReadOnlySessionBranch(snapshot, this.reader.getLeafId());
+      check(
+        persistedBranch.length === branch.length && persistedBranch.every((e, i) => e.id === branch[i].id),
+        "snapshot_ancestry_mismatch",
+        "Live branch is not the complete persisted ancestry for its claimed leaf.",
+      );
+      replay(persistedBranch);
+      const disk = new Map(persistedBranch.map((e) => [e.id, e]));
+      const known = new Map();
+      // Compare the live selected ancestry, not whichever branch was last written on disk.
+      for (const entry of branch) {
+        const captured = disk.get(entry.id);
+        check(
+          captured && canonical(captured) === canonical(entry),
+          "snapshot_divergence",
+          "Live ancestry is not fully established by the fresh persisted snapshot; reconcile the session before retrying.",
+        );
+        if (entry.type === "custom" && entry.customType === ROUTING_ENTRY) {
+          const event = parseRoutingEvent(entry.data);
+          known.set(eventKey(event), { value: eventValue(event), eventId: event.eventId, entryId: entry.id });
+        }
+      }
+      for (const [key, event] of this.attempted)
+        check(
+          known.get(key)?.value === eventValue(event) && known.get(key)?.eventId === event.eventId,
+          "append_acknowledgment_uncertain",
+          "The attempted routing event is not established by persisted readback.",
+        );
+      this.observed = known;
+      this.attempted.clear();
+      this.fault = undefined;
+      this.ready = true;
+      this.cachedEntries = [];
+      this.cachedState = replay([]);
+    } catch (error) {
+      this.block(
+        error instanceof RoutingError
+          ? error.code
+          : error instanceof ReadOnlySessionError
+            ? `${error.code}: ${error.message}`
+            : "snapshot_unavailable",
+      );
+      throw error;
+    }
+  }
+  append(event) {
+    const value = parseRoutingEvent(event),
+      key = eventKey(value),
+      body = eventValue(value);
+    if (this.blocked) throw new RoutingError("acknowledgment_uncertain", this.blocked);
+    const prior = this.state().events.get(key);
+    if (prior) {
+      check(eventValue(prior) === body, "operation_conflict");
+      const occurrence = this.reader
+        .getBranch()
+        .find(
+          (entry) =>
+            entry.type === "custom" && entry.customType === ROUTING_ENTRY && entry.data?.eventId === prior.eventId,
+        );
+      if (
+        this.observed.get(key)?.value !== body ||
+        this.observed.get(key)?.eventId !== prior.eventId ||
+        this.observed.get(key)?.entryId !== occurrence?.id
+      ) {
+        this.block("prior_acknowledgment_unclassified");
+        throw new RoutingError("acknowledgment_uncertain", this.blocked);
+      }
+      return prior;
+    }
+    // Validate the whole state transition before mutating Pi's session memory.
+    const candidate = reduce(this.state(), value);
+    const baseline = this.cachedEntries;
+    this.attempted.set(key, value);
+    try {
+      this.pi.appendEntry(ROUTING_ENTRY, value);
+      const found = this.reader
+        .getBranch()
+        .find((e) => e.type === "custom" && e.customType === ROUTING_ENTRY && e.data?.eventId === value.eventId);
+      check(found && eventValue(parseRoutingEvent(found.data)) === body, "append_not_observed");
+      this.observed.set(key, { value: body, eventId: value.eventId, entryId: found.id });
+      this.attempted.delete(key);
+      const branch = this.reader.getBranch();
+      const delta = branch.slice(baseline.length).filter((e) => e.type === "custom" && e.customType === ROUTING_ENTRY);
+      if (baseline.every((e, i) => branch[i] === e) && delta.length === 1 && delta[0].id === found.id) {
+        // Publish the already validated candidate only after acknowledged native append.
+        this.cachedState = candidate;
+        this.cachedEntries = [...branch];
+      }
+      return value;
+    } catch (error) {
+      this.block("append_acknowledgment_uncertain");
+      throw new RoutingError(
+        "acknowledgment_uncertain",
+        error instanceof Error ? error.message : "Pi append/readback did not acknowledge the event.",
+      );
+    }
+  }
+}

package/pi-extension/dist/session-sources/provenance.js

@@ -0,0 +1,32 @@
+import { isWorkerProfile } from "../cognitive-routing-v2/types.js";
+import { isTaskEvidence, textRef } from "./sources.js";
+export function annotateSources(messages, renderedSources, full, sources, instance) {
+  const annotated = [];
+  for (let i = 0; i < messages.length;) {
+    const group = [messages[i++]];
+    while (i < messages.length && messages[i].role === "toolResult") group.push(messages[i++]);
+    const rows = group.flatMap((message) => {
+      const s = renderedSources.get(message);
+      if (!s) return [];
+      const representation = full.has(s.ref) ? "full" : "structural only; omitted result bodies are not evidence";
+      const selection =
+        isWorkerProfile(s.producer) && isTaskEvidence(s) && full.has(s.ref)
+          ? "task evidence; selection checks apply"
+          : "not offered for new evidence selection";
+      return [
+        `${s.ref} | producer: ${s.producer === "common" ? "unknown/common (no observed routing profile)" : s.producer} | ${s.original ? "assistant-text" : s.message.role}${s.message.toolName ? ` | ${s.message.toolName}` : ""}${s.assignmentId ? ` | assignment: ${s.assignmentId}` : ""} | ${representation} | ${selection}${!s.original && full.has(s.ref) && sources.byRef.has(textRef(s.ref)) ? ` | visible text: ${textRef(s.ref)}` : ""}`,
+      ];
+    });
+    annotated.push(...group);
+    if (rows.length)
+      annotated.push({
+        role: "custom",
+        customType: "freeflow-routing-v2-refs",
+        display: false,
+        content: `Source provenance for the preceding message/exchange:\n${rows.join("\n")}`,
+        details: { routingInstance: instance },
+        timestamp: 0,
+      });
+  }
+  return annotated;
+}

package/pi-extension/dist/session-sources/read-only-session.js

@@ -0,0 +1,148 @@
+import { createHash } from "node:crypto";
+import { open, stat } from "node:fs/promises";
+import { TextDecoder } from "node:util";
+export class ReadOnlySessionError extends Error {
+  code;
+  line;
+  constructor(code, message, line) {
+    super(message);
+    this.code = code;
+    this.line = line;
+    this.name = "ReadOnlySessionError";
+  }
+}
+export const SESSION_READ_LIMITS = {
+  maxBytes: 512 * 1024 * 1024,
+  maxEntryBytes: 128 * 1024 * 1024,
+  maxEntries: 250000,
+};
+function decodeEntry(text, line, seen) {
+  let value;
+  try {
+    value = JSON.parse(text);
+  } catch {
+    throw new ReadOnlySessionError("invalid_json", "Incomplete or invalid session JSON.", line);
+  }
+  if (!value || Array.isArray(value) || typeof value !== "object" || typeof value.type !== "string")
+    throw new ReadOnlySessionError("invalid_entry", "Invalid session entry.", line);
+  if (line === 1) {
+    if (
+      value.type !== "session" ||
+      typeof value.id !== "string" ||
+      !value.id ||
+      ![2, 3].includes(value.version) ||
+      typeof value.cwd !== "string"
+    )
+      throw new ReadOnlySessionError("invalid_header", "A supported native session header is required.", line);
+  } else {
+    if (value.type === "session" || typeof value.id !== "string" || !value.id || seen.has(value.id))
+      throw new ReadOnlySessionError("invalid_id", "Missing, duplicate, or misplaced session identity.", line);
+    if (value.parentId !== null && (typeof value.parentId !== "string" || !seen.has(value.parentId)))
+      throw new ReadOnlySessionError("invalid_parent", "Parent is absent or occurs after its child.", line);
+    seen.add(value.id);
+  }
+  return value;
+}
+export function parseReadOnlySessionText(text) {
+  const lines = text.split("\n");
+  if (lines.at(-1) === "") lines.pop();
+  if (!lines.length || !lines[0]) throw new ReadOnlySessionError("empty", "Session snapshot is empty.");
+  const seen = new Set();
+  return lines.map((line, i) => decodeEntry(line, i + 1, seen));
+}
+export async function readOnlySessionSnapshot(path, options = {}) {
+  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.");
+  let file;
+  try {
+    file = await open(path, "r");
+    const before = await file.stat({ bigint: true });
+    if (!before.isFile()) throw new ReadOnlySessionError("read_limit", "Session is not a regular file.");
+    if (before.size > BigInt(limits.maxBytes))
+      throw new ReadOnlySessionError(
+        "read_limit",
+        `Session exceeds the supported ${limits.maxBytes} byte snapshot limit.`,
+      );
+    const hash = createHash("sha256"),
+      entries = [],
+      seen = new Set();
+    let total = 0,
+      lineBytes = 0,
+      parts = [];
+    const append = (part) => {
+      lineBytes += part.length;
+      if (lineBytes > limits.maxEntryBytes)
+        throw new ReadOnlySessionError(
+          "entry_limit",
+          `Session entry exceeds ${limits.maxEntryBytes} bytes.`,
+          entries.length + 1,
+        );
+      if (part.length) parts.push(part);
+    };
+    const decode = () => {
+      if (entries.length >= limits.maxEntries)
+        throw new ReadOnlySessionError("entry_count_limit", `Session exceeds ${limits.maxEntries} entries.`);
+      let text;
+      try {
+        text = new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(parts, lineBytes));
+      } catch {
+        throw new ReadOnlySessionError("invalid_encoding", "Session is not complete UTF-8.", entries.length + 1);
+      }
+      entries.push(decodeEntry(text, entries.length + 1, seen));
+      parts = [];
+      lineBytes = 0;
+    };
+    for (;;) {
+      const buffer = Buffer.alloc(64 * 1024),
+        { bytesRead } = await file.read(buffer, 0, buffer.length, null);
+      if (!bytesRead) break;
+      total += bytesRead;
+      if (total > limits.maxBytes)
+        throw new ReadOnlySessionError("read_limit", "Session grew beyond the supported snapshot limit.");
+      const bytes = buffer.subarray(0, bytesRead);
+      hash.update(bytes);
+      let start = 0,
+        end;
+      while ((end = bytes.indexOf(10, start)) !== -1) {
+        append(bytes.subarray(start, end));
+        decode();
+        start = end + 1;
+      }
+      append(bytes.subarray(start));
+    }
+    if (lineBytes) decode();
+    if (!entries.length) throw new ReadOnlySessionError("empty", "Session snapshot is empty.");
+    const after = await file.stat({ bigint: true }),
+      current = await stat(path, { bigint: true });
+    const signature = (v) => [v.dev, v.ino, v.size, v.mtimeNs, v.ctimeNs].join(":");
+    if (
+      signature(before) !== signature(after) ||
+      signature(after) !== signature(current) ||
+      after.size !== BigInt(total)
+    )
+      throw new ReadOnlySessionError("source_changed", "Session changed during snapshot capture.");
+    return { path, sessionId: entries[0].id, version: entries[0].version, hash: hash.digest("hex"), entries };
+  } catch (error) {
+    if (error instanceof ReadOnlySessionError) throw error;
+    throw new ReadOnlySessionError("read_failed", error instanceof Error ? error.message : String(error));
+  } finally {
+    await file?.close();
+  }
+}
+export function activeReadOnlySessionBranch(snapshot, leafId) {
+  if (leafId === null) return [];
+  const byId = new Map(snapshot.entries.slice(1).map((entry) => [entry.id, entry]));
+  const path = [];
+  const seen = new Set();
+  let cursor = leafId;
+  while (cursor !== null) {
+    const entry = byId.get(cursor);
+    if (!entry || seen.has(cursor))
+      throw new ReadOnlySessionError("ancestry_unavailable", "Requested native ancestry is unavailable.");
+    seen.add(cursor);
+    path.push(entry);
+    cursor = entry.parentId;
+  }
+  return path.reverse();
+}