pi-fabric 0.88.2 → 0.89.0

package/dist/chunks/{chunk-AIN5KTE6.js → chunk-GUQT67PQ.js}

@@ -4,13 +4,20 @@ import {
   DEFAULT_REGEX_MAX_HAYSTACK_TERMS,
   DEFAULT_REGEX_MAX_PATTERN_BYTES,
   DEFAULT_REGEX_TIMEOUT_MS,
+  MEMORY_CACHE_VERSION,
+  classifySessionTiers,
+  digestPolicy,
   fingerprintSource,
+  fitDigestCache,
   loadTieredIndex,
+  reconstructRecordsLineage,
   reconstructSessionLineage,
-  searchMemoryIndex
-} from "./chunk-LUADHXOA.js";
+  searchMemoryIndex,
+  shardPolicy
+} from "./chunk-YIDC2IVN.js";
 import {
   compareLexical,
+  foldSessionDigest,
   normalizeMemoryPhrase,
   tokenizeLexical
 } from "./chunk-U5FYOMG5.js";
@@ -19,11 +26,12 @@ import {
   enumerateAllSessions,
   resolveScope,
   resolveSessionTarget
-} from "./chunk-XMLNV3QH.js";
+} from "./chunk-TDCMU5L4.js";
 import {
   expandSessionEntriesChecked,
+  normalizeRecords,
   normalizeSession
-} from "./chunk-KWBZBSMX.js";
+} from "./chunk-MYCDJTSM.js";
 
 // src/memory/context.ts
 var RECALL_DEFAULT_PAGE_SIZE = 10;
@@ -75,17 +83,19 @@ var makeSnippet = (text, query, queryMode, maxChars) => {
     truncated: true
   };
 };
-var sourceFromSegment = (segment) => ({
+var sourceFromSegment = (segment, sourceId) => ({
   sessionId: boundedMetadata(segment.sessionId) ?? "",
   sessionFile: segment.sessionFile,
+  ...sourceId ? { source: sourceId } : {},
   sourceHash: segment.sourceHash,
   branches: segment.branches,
   lineageFingerprint: segment.lineageFingerprint,
   tier: segment.tier
 });
-var sourceFromDigest = (digest) => ({
+var sourceFromDigest = (digest, sourceId) => ({
   sessionId: boundedMetadata(digest.sessionId) ?? "",
   sessionFile: digest.sessionFile,
+  ...sourceId ? { source: sourceId } : {},
   sourceHash: digest.sourceHash,
   branches: digest.branches,
   lineageFingerprint: digest.lineageFingerprint,
@@ -93,14 +103,15 @@ var sourceFromDigest = (digest) => ({
 });
 var expandArgs = (source, entry) => ({
   session: source.sessionFile,
+  ...source.source ? { source: source.source } : {},
   expectedSourceHash: source.sourceHash,
   expectedLineageFingerprint: source.lineageFingerprint,
   branches: source.branches,
   indices: [entry.index]
 });
-var entryHit = (segment, item, query, queryMode, snippetChars) => {
+var entryHit = (segment, item, query, queryMode, snippetChars, sourceId) => {
   const entry = item.entry;
-  const source = sourceFromSegment(segment);
+  const source = sourceFromSegment(segment, sourceId);
   const snippet = makeSnippet(entry.text, query, queryMode, snippetChars);
   return {
     kind: "entry",
@@ -135,8 +146,8 @@ var hydrationArgs = (digest, request) => {
     expectedLineageFingerprint: digest.lineageFingerprint
   };
 };
-var sessionHit = (digest, request) => {
-  const source = sourceFromDigest(digest);
+var sessionHit = (digest, request, sourceId) => {
+  const source = sourceFromDigest(digest, sourceId);
   return {
     kind: "session",
     sessionId: source.sessionId,
@@ -185,7 +196,7 @@ var flattenCandidates = (result) => {
   recallCandidateCache.set(result, candidates);
   return candidates;
 };
-var materializeCandidate = (candidate, query, queryMode, snippetChars, request) => candidate.kind === "session" ? sessionHit(candidate.digest, request) : entryHit(candidate.segment, candidate.item, query, queryMode, snippetChars);
+var materializeCandidate = (candidate, query, queryMode, snippetChars, request, sourceId) => candidate.kind === "session" ? sessionHit(candidate.digest, request, sourceId) : entryHit(candidate.segment, candidate.item, query, queryMode, snippetChars, sourceId);
 var canonicalNextArgs = (request, offset) => {
   const { offset: _offset, ...base } = request;
   return { ...base, offset };
@@ -201,7 +212,8 @@ var presentRecall = (input) => {
         input.query,
         input.queryMode,
         input.snippetChars,
-        input.requestArgs
+        input.requestArgs,
+        input.requestArgs.source
       )
     );
     return {
@@ -308,6 +320,7 @@ var recallFailure = (error) => ({
 import path3 from "node:path";
 
 // src/memory/source-observation.ts
+import crypto from "node:crypto";
 import fs from "node:fs";
 import path2 from "node:path";
 var sourceIdentity = (file) => {
@@ -336,6 +349,21 @@ var observeSource = (file, branches, liveBranch) => {
     liveBranchSignature: branches === "active" ? liveBranchSignature(liveBranch) : null
   };
 };
+var hostIdentity = (revision, sourceHash) => {
+  const digest = crypto.createHash("sha256").update(`${revision}\0${sourceHash}`).digest("hex");
+  return {
+    device: BigInt(parseInt(digest.slice(0, 8), 16)),
+    inode: BigInt(parseInt(digest.slice(8, 16), 16)),
+    size: BigInt(parseInt(digest.slice(16, 24), 16)),
+    modifiedAt: BigInt(parseInt(digest.slice(24, 32), 16)),
+    changedAt: BigInt(parseInt(digest.slice(32, 40), 16))
+  };
+};
+var observeHostSource = (displayKey, revision, sourceHash) => ({
+  file: displayKey,
+  identity: hostIdentity(revision, sourceHash),
+  liveBranchSignature: null
+});
 var observeSources = (refs, branches, liveResolver) => {
   const observations = [];
   for (const ref of refs) {
@@ -443,6 +471,419 @@ var MemoryRequestCache = class {
   }
 };
 
+// src/memory/host-source.ts
+import crypto2 from "node:crypto";
+
+// src/memory/portable.ts
+var MEMORY_SOURCE_INTERFACE_VERSION = 1;
+var MemorySourceError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "MemorySourceError";
+  }
+};
+var SOURCE_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+var isRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+var assertValidSource = (source) => {
+  if (!isRecord(source) || typeof source !== "object") {
+    throw new TypeError("A portable memory source must be an object");
+  }
+  if (source.interfaceVersion !== MEMORY_SOURCE_INTERFACE_VERSION) {
+    throw new TypeError(
+      `Portable memory source interface version must be ${MEMORY_SOURCE_INTERFACE_VERSION}`
+    );
+  }
+  if (typeof source.id !== "string" || !SOURCE_ID_PATTERN.test(source.id)) {
+    throw new TypeError(
+      "Portable memory source id must be 1-128 chars of letters, digits, dot, underscore, or dash"
+    );
+  }
+  if (typeof source.listSessions !== "function" || typeof source.loadSession !== "function") {
+    throw new TypeError("A portable memory source requires listSessions and loadSession");
+  }
+};
+var defineMemorySource = (source) => {
+  assertValidSource(source);
+  return source;
+};
+var createMemorySourceRegistry = () => {
+  const sources = /* @__PURE__ */ new Map();
+  return {
+    register(source) {
+      assertValidSource(source);
+      sources.set(source.id, source);
+    },
+    get(id) {
+      return sources.get(id);
+    },
+    ids() {
+      return [...sources.keys()].sort();
+    }
+  };
+};
+
+// src/memory/host-source.ts
+var HOST_KEY_PREFIX = "memory-source:";
+var REASON_PATTERN = /^[a-z0-9_.:-]{1,64}$/;
+var hostDisplayKey = (sourceId, sessionKey) => `${HOST_KEY_PREFIX}${sourceId}/${sessionKey}`;
+var hostSessionKey = (sourceId, session) => {
+  const prefix = `${HOST_KEY_PREFIX}${sourceId}/`;
+  return session.startsWith(prefix) ? session.slice(prefix.length) : session;
+};
+var resolveRegisteredSource = (registry, sourceId) => {
+  const source = registry?.get(sourceId);
+  if (!source) throw new MemorySourceError("source_not_found", `Memory source not registered: ${sourceId}`);
+  return source;
+};
+var memorySourceFailure = (error) => error instanceof MemorySourceError ? { code: error.code, message: error.message } : null;
+var checkAbort = (signal) => {
+  if (signal?.aborted) throw new MemorySourceError("aborted", "Memory source call was aborted.");
+};
+var assertAuthorized = async (source, action, sessionKey) => {
+  if (!source.authorize) return;
+  let allowed;
+  try {
+    allowed = await source.authorize(action, sessionKey);
+  } catch {
+    throw new MemorySourceError("source_unauthorized", "Memory source authorization failed.");
+  }
+  if (allowed !== true) {
+    throw new MemorySourceError("source_unauthorized", "Memory source denied access.");
+  }
+};
+var coverageReasons = (coverage) => {
+  if (!coverage || coverage.complete !== false) return [];
+  const reason = typeof coverage.reason === "string" && REASON_PATTERN.test(coverage.reason) ? `source_coverage:${coverage.reason}` : "source_coverage_incomplete";
+  return [reason];
+};
+var asSessionKey = (value) => typeof value === "string" && value.length > 0 ? value : "";
+var normalizeListResponse = (response) => Array.isArray(response) ? { sessions: response, coverageReasons: [] } : { sessions: response.sessions, coverageReasons: coverageReasons(response.coverage) };
+var loadHostSnapshot = async (source, sessionKey, action, signal) => {
+  checkAbort(signal);
+  await assertAuthorized(source, action, sessionKey);
+  const response = await source.loadSession(sessionKey, signal === void 0 ? {} : { signal });
+  checkAbort(signal);
+  await assertAuthorized(source, action, sessionKey);
+  if (response === null || response === void 0) return null;
+  const key = asSessionKey(response.sessionKey);
+  const revision = asSessionKey(response.revision);
+  if (!revision || !Array.isArray(response.records) || key !== sessionKey) {
+    throw new MemorySourceError("invalid_source_response", "Memory source returned an invalid snapshot.");
+  }
+  if (!response.records.every((record) => record !== null && typeof record === "object" && !Array.isArray(record))) {
+    throw new MemorySourceError("invalid_source_response", "Memory source snapshot has non-object records.");
+  }
+  let records;
+  try {
+    records = JSON.parse(JSON.stringify(response.records));
+  } catch {
+    throw new MemorySourceError(
+      "invalid_source_response",
+      "Memory source snapshot records are not JSON-serializable."
+    );
+  }
+  return {
+    sourceId: source.id,
+    sessionKey,
+    displayKey: hostDisplayKey(source.id, sessionKey),
+    sessionId: response.sessionId ?? sessionKey,
+    revision,
+    metadata: { ...response.metadata ?? {} },
+    records,
+    coverageReasons: coverageReasons(response.coverage)
+  };
+};
+var listHostSnapshots = async (source, limit, action, signal) => {
+  checkAbort(signal);
+  await assertAuthorized(source, action, null);
+  const boundedLimit = Math.max(0, Math.floor(limit));
+  const listed = normalizeListResponse(
+    await source.listSessions(signal === void 0 ? { limit: boundedLimit } : { limit: boundedLimit, signal })
+  );
+  checkAbort(signal);
+  const snapshots = [];
+  const coverageReasons2 = new Set(listed.coverageReasons);
+  if (listed.sessions.length > boundedLimit) {
+    coverageReasons2.add("source_limit_exceeded");
+  }
+  for (const descriptor of listed.sessions.slice(0, boundedLimit)) {
+    checkAbort(signal);
+    const key = asSessionKey(descriptor.sessionKey);
+    if (!key) {
+      coverageReasons2.add("invalid_source_response");
+      continue;
+    }
+    const snapshot = await loadHostSnapshot(source, key, action, signal);
+    if (!snapshot) {
+      coverageReasons2.add("source_unavailable");
+      continue;
+    }
+    for (const reason of snapshot.coverageReasons) coverageReasons2.add(reason);
+    snapshots.push(snapshot);
+  }
+  if (snapshots.length === 0) {
+    await assertAuthorized(source, action, null);
+  }
+  return { snapshots, coverageReasons: [...coverageReasons2] };
+};
+var hostSourceState = (snapshot) => {
+  const canonical = JSON.stringify(snapshot.records);
+  const sourceHash = crypto2.createHash("sha256").update(`${snapshot.revision}\0${canonical}`).digest("hex");
+  return {
+    mtime: snapshot.metadata.updatedAt ?? 0,
+    size: Buffer.byteLength(canonical, "utf8"),
+    sourceHash
+  };
+};
+var hostRef = (snapshot) => ({
+  id: snapshot.sessionId,
+  file: snapshot.displayKey,
+  cwd: snapshot.metadata.cwd ?? "",
+  mtime: snapshot.metadata.updatedAt ?? 0
+});
+var hostLineage = (snapshot, branches) => reconstructRecordsLineage(snapshot.records, branches);
+var hostIdentity2 = (sessionFile, sessionId, cwd) => ({
+  sessionFile,
+  ...sessionId !== void 0 ? { sessionId } : {},
+  ...cwd !== void 0 ? { cwd } : {}
+});
+var mergedCoverage = (base, extra) => {
+  if (extra.length === 0) return base;
+  const reasons = [.../* @__PURE__ */ new Set([...base.reasons, ...extra])].sort();
+  return { complete: false, reasons };
+};
+var buildHostShard = (snapshot, options, tier, entryRange) => {
+  const state = hostSourceState(snapshot);
+  const lineage = hostLineage(snapshot, options.branches ?? "active");
+  const { entries, header, indexCoverage } = normalizeRecords(
+    snapshot.records,
+    hostIdentity2(snapshot.displayKey, snapshot.sessionId, snapshot.metadata.cwd),
+    options.maxEntryChars,
+    {
+      lineage,
+      indexThinking: options.indexThinking ?? false,
+      indexToolOutput: options.indexToolOutput ?? true
+    }
+  );
+  const selected = entryRange ? entries.filter((entry) => entry.index >= entryRange.first && entry.index <= entryRange.last) : entries;
+  return {
+    cacheVersion: MEMORY_CACHE_VERSION,
+    kind: "shard",
+    sessionFile: snapshot.displayKey,
+    sessionId: header?.sessionId ?? snapshot.sessionId,
+    mtime: state.mtime,
+    size: state.size,
+    sourceHash: state.sourceHash,
+    branches: lineage.branches,
+    lineageFingerprint: lineage.fingerprint,
+    policy: shardPolicy(options, lineage),
+    cacheBytes: 0,
+    cacheSourceRatio: 0,
+    entries: selected,
+    totalEntryCount: entries.length,
+    indexCoverage: mergedCoverage(indexCoverage, snapshot.coverageReasons),
+    tier
+  };
+};
+var buildHostDigest = (snapshot, options) => {
+  const state = hostSourceState(snapshot);
+  const lineage = hostLineage(snapshot, options.branches ?? "active");
+  const { entries, header, indexCoverage } = normalizeRecords(
+    snapshot.records,
+    hostIdentity2(snapshot.displayKey, snapshot.sessionId, snapshot.metadata.cwd),
+    Number.MAX_SAFE_INTEGER,
+    {
+      lineage,
+      indexThinking: options.indexThinking ?? false,
+      indexToolOutput: options.indexToolOutput ?? true
+    }
+  );
+  const digest = foldSessionDigest({
+    sessionId: header?.sessionId ?? snapshot.sessionId,
+    file: snapshot.displayKey,
+    cwd: header?.cwd ?? snapshot.metadata.cwd ?? "",
+    entries,
+    maxVocabularyBytes: options.maxColdVocabularyBytes ?? 512 * 1024,
+    normalizationCoverage: mergedCoverage(indexCoverage, snapshot.coverageReasons)
+  });
+  return fitDigestCache({
+    cacheVersion: MEMORY_CACHE_VERSION,
+    kind: "digest",
+    ...digest,
+    mtime: state.mtime,
+    size: state.size,
+    sourceHash: state.sourceHash,
+    branches: lineage.branches,
+    lineageFingerprint: lineage.fingerprint,
+    policy: digestPolicy(options, lineage),
+    cacheBytes: 0,
+    cacheSourceRatio: 0
+  }, options.maxColdCacheBytes ?? 1024 * 1024);
+};
+var loadHostTieredIndex = (snapshots, options, hydrate = false, entryRange, extraReasons = []) => {
+  const refs = snapshots.map(hostRef);
+  const tiers = classifySessionTiers(refs, options.hotSessions ?? 50);
+  const maxSessions = options.maxSyncSessions ?? 1e4;
+  const maxSourceBytes = options.maxSyncSourceBytes ?? 512 * 1024 * 1024;
+  const shards = [];
+  const digests = [];
+  const reasons = new Set(extraReasons);
+  let indexedSessions = 0;
+  let incompleteSessions = 0;
+  let processedSessions = 0;
+  let processedSourceBytes = 0;
+  const byKey = new Map(snapshots.map((snapshot) => [snapshot.displayKey, snapshot]));
+  for (const ref of refs) {
+    const snapshot = byKey.get(ref.file);
+    if (!snapshot) {
+      reasons.add("source_unavailable");
+      continue;
+    }
+    const size = hostSourceState(snapshot).size;
+    if (processedSessions >= maxSessions) {
+      reasons.add("max_sync_sessions");
+      continue;
+    }
+    const tier = tiers.get(ref.file) ?? "cold";
+    const sourceWorkBytes = size * (hydrate && tier === "cold" ? 6 : 3);
+    if (processedSourceBytes + sourceWorkBytes > maxSourceBytes) {
+      reasons.add("max_sync_source_bytes");
+      continue;
+    }
+    processedSessions += 1;
+    processedSourceBytes += sourceWorkBytes;
+    if (hydrate) {
+      if (tier === "cold") digests.push(buildHostDigest(snapshot, options));
+      const shard = buildHostShard(snapshot, options, "cold", entryRange);
+      shards.push(shard);
+      if (shard.sourceHash) indexedSessions += 1;
+      if (shard.sourceHash && !shard.indexCoverage.complete) {
+        incompleteSessions += 1;
+        for (const reason of shard.indexCoverage.reasons) reasons.add(reason);
+      }
+    } else if (tier === "hot") {
+      const shard = buildHostShard(snapshot, options, "hot");
+      shards.push(shard);
+      if (shard.sourceHash) indexedSessions += 1;
+      if (shard.sourceHash && !shard.indexCoverage.complete) {
+        incompleteSessions += 1;
+        for (const reason of shard.indexCoverage.reasons) reasons.add(reason);
+      }
+    } else {
+      const digest = buildHostDigest(snapshot, options);
+      digests.push(digest);
+      if (digest.sourceHash) indexedSessions += 1;
+      if (!digest.indexCoverage.complete) {
+        incompleteSessions += 1;
+        for (const reason of digest.indexCoverage.reasons) reasons.add(reason);
+      }
+    }
+  }
+  const eligibleSessions = refs.length;
+  const staleSessions = eligibleSessions - indexedSessions;
+  const coverage = {
+    complete: reasons.size === 0 && staleSessions === 0 && incompleteSessions === 0,
+    indexedSessions,
+    eligibleSessions,
+    staleSessions,
+    incompleteSessions,
+    reasons: [...reasons].sort()
+  };
+  return { shards, digests, refs, tiers, coverage };
+};
+var fileRecallPlan = (refs, context) => {
+  const liveResolver = liveBranchResolver(context);
+  return {
+    refs,
+    sessionKey: null,
+    observeAll: (branches) => observeSources(refs, branches, liveResolver),
+    stateFor: (ref) => fingerprintSource(ref.file),
+    lineageFor: (ref, branches) => reconstructSessionLineage(ref.file, branches, liveResolver?.(ref.file)),
+    loadIndex: (options, hydrate, entryRange) => loadTieredIndex(refs, resolveTierRefs(refs, context), options, hydrate, entryRange)
+  };
+};
+var hostRecallPlan = async (source, sourceId, sessionKey, context, signal) => {
+  const loaded = sessionKey !== null ? await (async () => {
+    const snapshot = await loadHostSnapshot(source, sessionKey, "recall", signal);
+    return snapshot ? { snapshots: [snapshot], coverageReasons: [] } : null;
+  })() : await listHostSnapshots(source, context.config.maxSessions, "recall", signal);
+  if (!loaded) throw new MemorySourceError("session_not_found", `Session not found in source ${sourceId}: ${sessionKey}`);
+  const snapshots = loaded.snapshots;
+  const refs = snapshots.map(hostRef);
+  const byKey = new Map(snapshots.map((snapshot) => [snapshot.displayKey, snapshot]));
+  const stateByKey = /* @__PURE__ */ new Map();
+  const stateOf = (snapshot) => {
+    let state = stateByKey.get(snapshot.displayKey);
+    if (!state) {
+      state = hostSourceState(snapshot);
+      stateByKey.set(snapshot.displayKey, state);
+    }
+    return state;
+  };
+  return {
+    refs,
+    sessionKey,
+    observeAll: (branches) => snapshots.map((snapshot) => observeHostSource(snapshot.displayKey, snapshot.revision, stateOf(snapshot).sourceHash)),
+    stateFor: (ref) => {
+      const snapshot = byKey.get(ref.file);
+      return snapshot ? stateOf(snapshot) : null;
+    },
+    lineageFor: (ref, branches) => {
+      const snapshot = byKey.get(ref.file);
+      return snapshot ? hostLineage(snapshot, branches) : reconstructSessionLineage(ref.file, branches);
+    },
+    loadIndex: (options, hydrate, entryRange) => loadHostTieredIndex(snapshots, options, hydrate, entryRange, loaded.coverageReasons)
+  };
+};
+var fileExpansionAccess = (session, context) => {
+  const ref = resolveSessionTarget(context.agentDir, session);
+  if (!ref) return null;
+  const liveResolver = liveBranchResolver(context);
+  return {
+    ref,
+    state: () => fingerprintSource(ref.file),
+    lineage: (branches) => reconstructSessionLineage(ref.file, branches, liveResolver?.(ref.file)),
+    observe: (branches) => observeSource(ref.file, branches, branches === "active" ? liveResolver?.(ref.file) : void 0),
+    normalizeFull: (branches, policy, lineage) => {
+      const resolvedLineage = lineage ?? reconstructSessionLineage(ref.file, branches, liveResolver?.(ref.file));
+      const normalized = normalizeSession(ref.file, Number.MAX_SAFE_INTEGER, {
+        lineage: resolvedLineage,
+        ...policy
+      });
+      return normalized.header === null && normalized.entries.length === 0 && normalized.indexCoverage.reasons.includes("source_unavailable") ? null : { entries: normalized.entries, indexCoverage: normalized.indexCoverage };
+    }
+  };
+};
+var hostExpansionAccess = async (sourceId, session, context, signal) => {
+  const source = resolveRegisteredSource(context.sources, sourceId);
+  const sessionKey = hostSessionKey(sourceId, session);
+  const snapshot = await loadHostSnapshot(source, sessionKey, "expand", signal);
+  if (!snapshot) {
+    throw new MemorySourceError("session_not_found", `Session not found in source ${sourceId}: ${sessionKey}`);
+  }
+  const state = hostSourceState(snapshot);
+  const ref = hostRef(snapshot);
+  return {
+    ref,
+    state: () => state,
+    lineage: (branches) => hostLineage(snapshot, branches),
+    observe: () => observeHostSource(snapshot.displayKey, snapshot.revision, state.sourceHash),
+    normalizeFull: (branches, policy) => {
+      const normalized = normalizeRecords(
+        snapshot.records,
+        hostIdentity2(snapshot.displayKey, snapshot.sessionId, snapshot.metadata.cwd),
+        Number.MAX_SAFE_INTEGER,
+        { lineage: hostLineage(snapshot, branches), ...policy }
+      );
+      return {
+        entries: normalized.entries,
+        indexCoverage: mergedCoverage(normalized.indexCoverage, snapshot.coverageReasons)
+      };
+    }
+  };
+};
+
 // src/memory/recall-service.ts
 async function processMemoryRecall(args, invocationContext, context, cache) {
   const query = typeof args.query === "string" ? args.query : void 0;
@@ -478,15 +919,38 @@ async function processMemoryRecall(args, invocationContext, context, cache) {
   const offset = typeof args.offset === "number" && args.offset >= 0 ? Math.floor(args.offset) : void 0;
   const pageSize = typeof args.pageSize === "number" && args.pageSize >= 1 ? Math.min(Math.floor(args.pageSize), RECALL_MAX_PAGE_SIZE) : RECALL_DEFAULT_PAGE_SIZE;
   const snippetChars = typeof args.snippetChars === "number" && args.snippetChars >= 80 ? Math.min(Math.floor(args.snippetChars), RECALL_MAX_SNIPPET_CHARS) : RECALL_DEFAULT_SNIPPET_CHARS;
-  const refs = resolveRefs(scope, context, false);
-  const liveResolver = liveBranchResolver(context);
+  const sourceId = typeof args.source === "string" && args.source.length > 0 ? args.source : void 0;
+  let plan;
+  if (sourceId !== void 0) {
+    if (scope !== void 0 && scope !== `source:${sourceId}` && !scope.startsWith("session:")) {
+      throw new Error(
+        "memory.recall scope must name the selected source, one of its sessions, or be omitted"
+      );
+    }
+    try {
+      plan = await hostRecallPlan(
+        resolveRegisteredSource(context.sources, sourceId),
+        sourceId,
+        scope?.startsWith("session:") ? scope.slice("session:".length).trim() : null,
+        context,
+        invocationContext.signal
+      );
+    } catch (error) {
+      const failure = memorySourceFailure(error);
+      if (!failure) throw error;
+      return recallFailure(failure);
+    }
+  } else {
+    plan = fileRecallPlan(resolveRefs(scope, context, false), context);
+  }
+  const refs = plan.refs;
   const options = resolveIndexOptions(
     context.config,
     context.agentDir,
     branches,
-    liveResolver
+    sourceId === void 0 ? liveBranchResolver(context) : void 0
   );
-  const hydrate = scope?.trim().startsWith("session:") ?? false;
+  const hydrate = sourceId !== void 0 ? plan.sessionKey !== null : scope?.trim().startsWith("session:") ?? false;
   if ((expectedSourceHash !== void 0 || expectedLineageFingerprint !== void 0) && !hydrate) {
     throw new Error("memory.recall integrity expectations require scope session:<id-or-path>");
   }
@@ -514,13 +978,14 @@ async function processMemoryRecall(args, invocationContext, context, cache) {
   if (since !== void 0) filters.since = since;
   if (until !== void 0) filters.until = until;
   const baseRequestArgs = {
+    ...sourceId ? { source: sourceId } : {},
     ...query === void 0 ? {} : { query },
     queryMode,
     ...queryMode === "literal" ? { queryMatch } : {},
     ...expectedSourceHash ? { expectedSourceHash } : {},
     ...expectedLineageFingerprint ? { expectedLineageFingerprint } : {},
     branches,
-    scope: scope ?? "session",
+    scope: sourceId ? plan.sessionKey !== null ? `session:${plan.refs[0]?.file ?? plan.sessionKey}` : `source:${sourceId}` : scope ?? "session",
     ...offset === void 0 ? {} : { offset },
     pageSize,
     snippetChars,
@@ -539,7 +1004,7 @@ async function processMemoryRecall(args, invocationContext, context, cache) {
       searchResult.matchMode === "structural" ? `memory.recall: ${searchResult.matchedCount} structural matches` : searchResult.matchMode === "combined" ? `memory.recall: ${searchResult.matchedCount} filtered matches` : query ? `memory.recall: ${searchResult.matchedCount} matches` : `memory.recall: ${searchResult.matchedCount} recent entries`
     );
   };
-  const observationsBefore = observeSources(refs, branches, liveResolver);
+  const observationsBefore = await plan.observeAll(branches);
   const cached = offset === void 0 ? void 0 : cache.cachedRecallContinuation(
     recallContinuationKey(baseRequestArgs),
     observationsBefore
@@ -555,7 +1020,7 @@ async function processMemoryRecall(args, invocationContext, context, cache) {
       snippetChars,
       requestArgs: cached.requestArgs
     });
-    const observationsAfterCachedPage = observeSources(refs, branches, liveResolver);
+    const observationsAfterCachedPage = await plan.observeAll(branches);
     if (observationsBefore && observationsAfterCachedPage && sameSourceObservations(observationsBefore, observationsAfterCachedPage)) {
       if (response2.next === null) cache.forgetRecallContinuation(cached);
       updateProgress(cached.result);
@@ -564,12 +1029,8 @@ async function processMemoryRecall(args, invocationContext, context, cache) {
     cache.forgetRecallContinuation(cached);
   }
   if (hydrate && refs[0]) {
-    const state = fingerprintSource(refs[0].file);
-    const lineage = reconstructSessionLineage(
-      refs[0].file,
-      branches,
-      liveResolver?.(refs[0].file)
-    );
+    const state = plan.stateFor(refs[0]);
+    const lineage = plan.lineageFor(refs[0], branches);
     const sourceChanged = expectedSourceHash !== void 0 && state?.sourceHash !== expectedSourceHash;
     const lineageChanged = expectedLineageFingerprint !== void 0 && lineage.fingerprint !== expectedLineageFingerprint;
     if (state && (sourceChanged || lineageChanged)) {
@@ -582,13 +1043,7 @@ async function processMemoryRecall(args, invocationContext, context, cache) {
       ));
     }
   }
-  const index = loadTieredIndex(
-    refs,
-    resolveTierRefs(refs, context),
-    options,
-    hydrate,
-    selectedRange
-  );
+  const index = plan.loadIndex(options, hydrate, selectedRange);
   const hydratedShard = index.shards[0];
   const hydratedSourceChanged = expectedSourceHash !== void 0 && hydratedShard?.sourceHash !== expectedSourceHash;
   const hydratedLineageChanged = expectedLineageFingerprint !== void 0 && hydratedShard?.lineageFingerprint !== expectedLineageFingerprint;
@@ -652,7 +1107,7 @@ async function processMemoryRecall(args, invocationContext, context, cache) {
     snippetChars,
     requestArgs
   });
-  const observationsAfter = observeSources(refs, branches, liveResolver);
+  const observationsAfter = await plan.observeAll(branches);
   if (response.next !== null && observationsBefore && observationsAfter && sameSourceObservations(observationsBefore, observationsAfter)) {
     cache.rememberRecallContinuation({
       key: recallContinuationKey(requestArgs),
@@ -668,8 +1123,9 @@ async function processMemoryRecall(args, invocationContext, context, cache) {
 }
 
 // src/memory/expand-service.ts
-async function processMemoryExpand(args, context, cache) {
+async function processMemoryExpand(args, context, cache, signal) {
   const session = typeof args.session === "string" ? args.session : "";
+  const sourceId = typeof args.source === "string" && args.source.length > 0 ? args.source : void 0;
   const expectedSourceHash = typeof args.expectedSourceHash === "string" ? args.expectedSourceHash : void 0;
   const expectedLineageFingerprint = typeof args.expectedLineageFingerprint === "string" ? args.expectedLineageFingerprint : void 0;
   const branches = parseBranches(args.branches, "memory.expand");
@@ -708,17 +1164,27 @@ async function processMemoryExpand(args, context, cache) {
   const textOffset = numeric(args.textOffset, 0, Number.MAX_SAFE_INTEGER);
   const maxChars = Math.max(256, numeric(args.maxChars, EXPAND_DEFAULT_MAX_CHARS, EXPAND_MAX_CHARS));
   const maxEntries = Math.max(1, numeric(args.maxEntries, EXPAND_DEFAULT_MAX_ENTRIES, EXPAND_MAX_ENTRIES));
-  const ref = resolveSessionTarget(context.agentDir, session);
-  if (!ref) {
+  let access;
+  if (sourceId !== void 0) {
+    try {
+      access = await hostExpansionAccess(sourceId, session, context, signal);
+    } catch (error) {
+      const failure = memorySourceFailure(error);
+      if (!failure) throw error;
+      return { session, error: failure, entries: [] };
+    }
+  } else {
+    access = fileExpansionAccess(session, context);
+  }
+  if (!access) {
     return {
       session,
       error: { code: "session_not_found", message: `Session not found: ${session}` },
       entries: []
     };
   }
-  const liveResolver = liveBranchResolver(context);
-  const observedLiveBranch = branches === "active" ? liveResolver?.(ref.file) : void 0;
-  const observedSource = observeSource(ref.file, branches, observedLiveBranch);
+  const ref = access.ref;
+  const observedSource = access.observe(branches);
   let snapshot = cache.cachedExpansionSnapshot(ref.file, branches, observedSource);
   if (snapshot) {
     const sourceChanged = expectedSourceHash !== void 0 && snapshot.sourceHash !== expectedSourceHash;
@@ -739,7 +1205,7 @@ async function processMemoryExpand(args, context, cache) {
     }
   }
   if (!snapshot) {
-    const initialState = fingerprintSource(ref.file);
+    const initialState = access.state();
     if (!initialState) {
       return {
         session: ref.file,
@@ -747,12 +1213,7 @@ async function processMemoryExpand(args, context, cache) {
         entries: []
       };
     }
-    const initialLiveBranch = branches === "active" ? liveResolver?.(ref.file) : void 0;
-    const initialLineage = reconstructSessionLineage(
-      ref.file,
-      branches,
-      initialLiveBranch
-    );
+    const initialLineage = access.lineage(branches);
     const sourceChanged = expectedSourceHash !== void 0 && initialState.sourceHash !== expectedSourceHash;
     const lineageChanged = expectedLineageFingerprint !== void 0 && initialLineage.fingerprint !== expectedLineageFingerprint;
     if (sourceChanged || lineageChanged) {
@@ -769,23 +1230,28 @@ async function processMemoryExpand(args, context, cache) {
         entries: []
       };
     }
-    const normalized = normalizeSession(
-      ref.file,
-      Number.MAX_SAFE_INTEGER,
-      {
-        lineage: initialLineage,
-        indexThinking: true,
-        indexToolOutput: true
-      }
-    ).entries;
-    const finalState2 = fingerprintSource(ref.file);
-    const finalLiveBranch = branches === "active" ? liveResolver?.(ref.file) : void 0;
-    const finalLineage2 = reconstructSessionLineage(
-      ref.file,
+    const normalizedFull = access.normalizeFull(
       branches,
-      finalLiveBranch
+      { indexThinking: true, indexToolOutput: true },
+      initialLineage
     );
-    const finalObservation = observeSource(ref.file, branches, finalLiveBranch);
+    if (!normalizedFull) {
+      return {
+        session: ref.file,
+        error: stalePointerError(
+          ref.file,
+          expectedSourceHash ?? initialState.sourceHash,
+          initialState.sourceHash,
+          expectedLineageFingerprint ?? initialLineage.fingerprint,
+          initialLineage.fingerprint
+        ),
+        entries: []
+      };
+    }
+    const normalized = normalizedFull.entries;
+    const finalState2 = access.state();
+    const finalLineage2 = access.lineage(branches);
+    const finalObservation = access.observe(branches);
     if (!finalState2 || !finalObservation || finalState2.sourceHash !== initialState.sourceHash || finalLineage2.fingerprint !== initialLineage.fingerprint) {
       return {
         session: ref.file,
@@ -994,6 +1460,7 @@ async function processMemoryExpand(args, context, cache) {
   const responseAt = (records, cursor2) => {
     const hasNext = cursor2.position < selected.length;
     const nextArgs = hasNext ? {
+      ...sourceId ? { source: sourceId } : {},
       session: ref.file,
       expectedSourceHash: finalState.sourceHash,
       expectedLineageFingerprint: finalLineage.fingerprint,
@@ -1071,12 +1538,11 @@ async function processMemoryExpand(args, context, cache) {
       response = responseAt(output, cursor);
     }
   }
-  const endingLiveBranch = branches === "active" ? liveResolver?.(ref.file) : void 0;
-  const endingObservation = observeSource(ref.file, branches, endingLiveBranch);
+  const endingObservation = access.observe(branches);
   if (!endingObservation || !sameSourceObservation(snapshot.observation, endingObservation)) {
     cache.forgetExpansionSnapshot(snapshot);
-    const actualState = fingerprintSource(ref.file);
-    const actualLineage = reconstructSessionLineage(ref.file, branches, endingLiveBranch);
+    const actualState = access.state();
+    const actualLineage = access.lineage(branches);
     if (!actualState || !endingObservation || actualState.sourceHash !== snapshot.sourceHash || actualLineage.fingerprint !== snapshot.lineageFingerprint) {
       return {
         session: ref.file,
@@ -1102,10 +1568,51 @@ async function processMemoryExpand(args, context, cache) {
 }
 
 // src/memory/sessions-service.ts
-async function processMemorySessions(args, context) {
+async function processMemorySessions(args, context, signal) {
+  const sourceId = typeof args.source === "string" && args.source.length > 0 ? args.source : void 0;
   const scope = typeof args.scope === "string" ? args.scope : void 0;
   const branches = parseBranches(args.branches, "memory.sessions");
   const limit = typeof args.limit === "number" && Number.isSafeInteger(args.limit) && args.limit >= 1 ? Math.min(args.limit, SESSIONS_MAX) : SESSIONS_MAX;
+  if (sourceId !== void 0) {
+    try {
+      const source = resolveRegisteredSource(context.sources, sourceId);
+      const { snapshots, coverageReasons: coverageReasons2 } = await listHostSnapshots(source, limit, "list", signal);
+      const options2 = resolveIndexOptions(context.config, context.agentDir, branches);
+      const index2 = loadHostTieredIndex(snapshots, options2, false, void 0, coverageReasons2);
+      const shards2 = new Map(index2.shards.map((shard) => [shard.sessionFile, shard]));
+      const digests2 = new Map(index2.digests.map((digest) => [digest.file, digest]));
+      const sessions2 = snapshots.map((snapshot) => {
+        const tier = index2.tiers.get(snapshot.displayKey) ?? "cold";
+        const shard = shards2.get(snapshot.displayKey);
+        const digest = digests2.get(snapshot.displayKey);
+        return {
+          id: shard?.sessionId ?? digest?.sessionId ?? snapshot.sessionId,
+          file: snapshot.displayKey,
+          cwd: digest?.cwd ?? snapshot.metadata.cwd ?? "",
+          mtime: snapshot.metadata.updatedAt ?? 0,
+          entryCount: shard?.entries.length ?? digest?.entryCount ?? 0,
+          tier,
+          branches,
+          lineageFingerprint: shard?.lineageFingerprint ?? digest?.lineageFingerprint ?? null
+        };
+      });
+      return {
+        scope: `source:${sourceId}`,
+        branches,
+        sessions: sessions2,
+        ...index2.coverage.complete ? {} : { coverage: index2.coverage }
+      };
+    } catch (error) {
+      const failure = memorySourceFailure(error);
+      if (!failure) throw error;
+      return {
+        scope: `source:${sourceId}`,
+        branches,
+        sessions: [],
+        error: failure
+      };
+    }
+  }
   const refs = resolveRefs(scope, context, true).slice(0, limit);
   const options = resolveIndexOptions(
     context.config,
@@ -1569,6 +2076,11 @@ var sessionsOutputSchema = {
     error: errorOutputSchema
   }
 };
+var SOURCE_ARG_SCHEMA = {
+  type: "string",
+  minLength: 1,
+  description: "Registered portable memory source id. When set, the call resolves against that source only \u2014 filesystem scopes are never consulted and there is no filesystem fallback."
+};
 var descriptors = [
   {
     name: "recall",
@@ -1576,6 +2088,7 @@ var descriptors = [
     inputSchema: {
       type: "object",
       properties: {
+        source: SOURCE_ARG_SCHEMA,
         query: { type: "string", maxLength: 4096 },
         queryMode: {
           type: "string",
@@ -1684,7 +2197,8 @@ var descriptors = [
     inputSchema: {
       type: "object",
       properties: {
-        session: { type: "string", description: "Exact session file path or unambiguous id." },
+        source: SOURCE_ARG_SCHEMA,
+        session: { type: "string", description: "Exact session file path, unambiguous id, or source session key." },
         expectedSourceHash: {
           type: "string",
           description: "SHA-256 from a prior pointer; stale sources are refused."
@@ -1762,6 +2276,7 @@ var descriptors = [
     inputSchema: {
       type: "object",
       properties: {
+        source: SOURCE_ARG_SCHEMA,
         scope: { type: "string" },
         branches: {
           type: "string",
@@ -1797,6 +2312,12 @@ var normalizeMemoryArgs = actionArgNormalizer(
   () => descriptors,
   MEMORY_ARG_NORMALIZATION
 );
+var memoryActionSchemas = Object.fromEntries(
+  descriptors.map((descriptor) => [
+    descriptor.name,
+    { inputSchema: descriptor.inputSchema, outputSchema: descriptor.outputSchema }
+  ])
+);
 var MemoryProvider = class {
   constructor(context) {
     this.context = context;
@@ -1822,9 +2343,9 @@ var MemoryProvider = class {
         case "recall":
           return await processMemoryRecall(args, invocationContext, this.context, this.cache);
         case "expand":
-          return await processMemoryExpand(args, this.context, this.cache);
+          return await processMemoryExpand(args, this.context, this.cache, invocationContext.signal);
         case "sessions":
-          return await processMemorySessions(args, this.context);
+          return await processMemorySessions(args, this.context, invocationContext.signal);
         default:
           throw new Error(`Unknown memory action: ${actionName}`);
       }
@@ -1848,7 +2369,16 @@ var MemoryProvider = class {
 export {
   uniqueDeclaredKeyForSpelling,
   actionArgNormalizer,
+  MemoryRequestCache,
+  MEMORY_SOURCE_INTERFACE_VERSION,
+  MemorySourceError,
+  defineMemorySource,
+  createMemorySourceRegistry,
+  processMemoryRecall,
+  processMemoryExpand,
+  processMemorySessions,
   normalizeMemoryArgs,
+  memoryActionSchemas,
   MemoryProvider
 };
-//# sourceMappingURL=chunk-AIN5KTE6.js.map
+//# sourceMappingURL=chunk-GUQT67PQ.js.map