sentinelayer-cli 0.46.5 → 0.48.0

package/src/engram/source-intake.js

@@ -0,0 +1,251 @@
+/**
+ * EW04 source-byte intake. The caller owns the source registry, origin allowlist,
+ * authorization decision and byte reader. In particular, `read` must be a
+ * trusted connector (for example, a repository blob reader); this module does
+ * not turn a URL from page content into a network request.
+ *
+ * Capture is deliberately before extraction: the returned bytes and digest are
+ * the evidence an extractor must cite. A schema-valid snapshot alone does not
+ * make extracted assertions authoritative.
+ */
+import { createHash } from "node:crypto";
+import { isIP } from "node:net";
+import { sourceSnapshotSchema } from "./contracts/source-snapshot.js";
+
+export const MAX_SOURCE_BYTES = 1024 * 1024;
+const DEFAULT_SOURCE_BYTES = 256 * 1024;
+const TEXT_TYPES = new Set(["text/plain", "text/html", "application/json"]);
+// Public guides may name credential variables. Reject credential-shaped values
+// without treating a variable name such as AIDENID_API_KEY as a leaked key.
+const CREDENTIAL_VALUES = [
+  /(?:gh[pousr]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,}|sk-(?:proj-|ant-)?[A-Za-z0-9_-]{20,})/,
+  /(?:AKIA[0-9A-Z]{16}|-----BEGIN [A-Z ]+PRIVATE KEY-----|xox[baprs]-[A-Za-z0-9-]{10,}|AIza[0-9A-Za-z_-]{35})/,
+  /eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{6,}/,
+  /authorization\s*:\s*bearer\s+[A-Za-z0-9._~+/-]{24,}/i,
+  // The key may be quoted, as in JSON ("api_key": "...") or YAML ('token': ...).
+  /(?:api[_-]?key|secret|token|password)["']?\s*[:=]\s*["']?[A-Za-z0-9._~+/-]{24,}/i,
+];
+
+export class SourceIntakeError extends Error {
+  constructor(code) {
+    super(code);
+    this.name = "SourceIntakeError";
+    this.code = code;
+  }
+}
+
+const OWN_ERRORS = new WeakSet();
+const CODES = new Set([
+  "invalid_source_limit", "source_access_denied", "source_not_approved",
+  "source_rejected", "source_too_large", "source_unavailable",
+]);
+
+function reject(code) {
+  // Frozen: a caller that kept an error from an earlier call cannot rewrite its message or code and replay it.
+  const error = Object.freeze(new SourceIntakeError(code));
+  OWN_ERRORS.add(error);
+  throw error;
+}
+
+function approvedUrl(raw, allowedOrigins) {
+  if (typeof raw !== "string" || !(allowedOrigins instanceof Set)) reject("source_not_approved");
+  let url;
+  try {
+    url = new URL(raw);
+  } catch {
+    reject("source_not_approved");
+  }
+  if (
+    url.href !== raw || url.protocol !== "https:" || url.username || url.password ||
+    url.search || url.hash || isIP(url.hostname.replace(/^\[|\]$/g, "")) || !allowedOrigins.has(url.origin)
+  ) reject("source_not_approved");
+  return url.href;
+}
+
+function unchangedApprovedSource(current, approved, allowedOrigins) {
+  try {
+    return current?.tenantScope === approved.tenantScope &&
+      current.visibility === approved.visibility &&
+      current.version === approved.version &&
+      current.sourceType === approved.sourceType &&
+      current.mediaType === approved.mediaType &&
+      approvedUrl(current.url, allowedOrigins) === approved.url;
+  } catch {
+    return false;
+  }
+}
+
+// The TypedArray intrinsic getters: a reader-supplied view can shadow .byteLength/.byteOffset/.buffer with
+// own properties, so the cap and the copy read the real values through these, never through the object.
+const TYPED_ARRAY = Object.getPrototypeOf(Uint8Array.prototype);
+const intrinsic = (name) => Object.getOwnPropertyDescriptor(TYPED_ARRAY, name).get;
+const VIEW_LENGTH = intrinsic("byteLength");
+const VIEW_OFFSET = intrinsic("byteOffset");
+const VIEW_BUFFER = intrinsic("buffer");
+// A stream may only yield this many chunks in total, so endless empty chunks cannot hold a capture open.
+export const MAX_SOURCE_CHUNKS = 4096;
+
+function copyView(view) {
+  const length = Reflect.apply(VIEW_LENGTH, view, []);
+  return { length, copy: () => Buffer.from(new Uint8Array(Reflect.apply(VIEW_BUFFER, view, []), Reflect.apply(VIEW_OFFSET, view, []), length)) };
+}
+
+async function boundedBytes(body, limit) {
+  if (body instanceof Uint8Array) {
+    const view = copyView(body);
+    if (view.length > limit) reject("source_too_large");
+    return view.copy();
+  }
+  if (!body || typeof body[Symbol.asyncIterator] !== "function") reject("source_rejected");
+  const chunks = [];
+  let length = 0;
+  let count = 0;
+  for await (const chunk of body) {
+    if (!(chunk instanceof Uint8Array)) reject("source_rejected");
+    count += 1;
+    if (count > MAX_SOURCE_CHUNKS) reject("source_too_large");
+    const view = copyView(chunk);
+    if (view.length === 0) continue; // never retain empty chunks
+    length += view.length;
+    if (length > limit) reject("source_too_large");
+    chunks.push(view.copy());
+  }
+  return Buffer.concat(chunks, length);
+}
+
+/**
+ * Capture a registered source into an EW02 SourceSnapshot and bounded bytes.
+ * `authorize` must consult the real tenant policy and is called again before
+ * returning captured bytes; `sources` and
+ * `allowedOrigins` must be maintained by the site owner, not by page content.
+ * `read` receives the approved URL and immutable source version, and must not
+ * follow redirects. It must report the actual version of the returned bytes,
+ * not echo the requested version; only the trusted connector can make that
+ * assertion. Its result must also report the final URL, status and media type.
+ */
+export async function captureSourceBytes({
+  sourceId,
+  tenantScope,
+  sources,
+  allowedOrigins,
+  authorize,
+  read,
+  capturedAt = () => new Date().toISOString(),
+  maxBytes = DEFAULT_SOURCE_BYTES,
+} = {}) {
+  if (
+    typeof sourceId !== "string" || !sourceId ||
+    typeof tenantScope !== "string" || !tenantScope ||
+    typeof authorize !== "function"
+  ) reject("source_access_denied");
+  if (!Number.isInteger(maxBytes) || maxBytes < 1 || maxBytes > MAX_SOURCE_BYTES) {
+    reject("invalid_source_limit");
+  }
+
+  // No source lookup or reader invocation until the tenant policy grants access.
+  let permitted = false;
+  try {
+    permitted = await authorize({ tenantScope, sourceId });
+  } catch {
+    reject("source_access_denied");
+  }
+  if (permitted !== true) reject("source_access_denied");
+
+  let approved;
+  try {
+    const source = sources instanceof Map ? sources.get(sourceId) : undefined;
+    approved = source && Object.freeze({
+      tenantScope: source.tenantScope,
+      visibility: source.visibility,
+      url: source.url,
+      version: source.version,
+      sourceType: source.sourceType,
+      mediaType: source.mediaType,
+    });
+  } catch {
+    reject("source_not_approved");
+  }
+  if (!approved || approved.tenantScope !== tenantScope || approved.visibility !== "public") {
+    reject("source_not_approved");
+  }
+  const url = approvedUrl(approved.url, allowedOrigins);
+  if (typeof approved.version !== "string" || !approved.version ||
+      (approved.sourceType !== "api" && approved.sourceType !== "ingest" && approved.sourceType !== "import") ||
+      !TEXT_TYPES.has(approved.mediaType) ||
+      typeof read !== "function") reject("source_not_approved");
+
+  let response;
+  try {
+    response = await read({ sourceId, tenantScope, url, version: approved.version, maxBytes });
+  } catch {
+    reject("source_unavailable");
+  }
+  let declaredLength;
+  try {
+    declaredLength = response?.contentLength;
+    if (
+      response?.status !== 200 || response.url !== url || response.version !== approved.version ||
+      typeof response.mediaType !== "string" ||
+      response.mediaType.split(";", 1)[0].trim().toLowerCase() !== approved.mediaType.toLowerCase() ||
+      (declaredLength !== undefined &&
+        (!Number.isSafeInteger(declaredLength) || declaredLength < 0 || declaredLength > maxBytes))
+    ) reject("source_rejected");
+  } catch {
+    reject("source_rejected");
+  }
+
+  let bytes;
+  try {
+    bytes = await boundedBytes(response.body, maxBytes);
+  } catch (error) {
+    // Never rethrow the caught object: a body stream can throw anything, including one of our own earlier errors.
+    // Re-raise only a fresh error carrying an allow-listed code.
+    if (OWN_ERRORS.has(error) && CODES.has(error.code)) reject(error.code);
+    reject("source_unavailable");
+  }
+  if (declaredLength !== undefined && declaredLength !== bytes.length) {
+    reject("source_rejected");
+  }
+  let text;
+  try {
+    text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  } catch {
+    reject("source_rejected");
+  }
+  // This first slice accepts public text only. A private/authenticated connector
+  // needs its own grant and content policy; a token in public source is denied.
+  if (CREDENTIAL_VALUES.some((pattern) => pattern.test(text))) reject("source_rejected");
+
+  let snapshot;
+  try {
+    snapshot = sourceSnapshotSchema.parse({
+      sourceId,
+      sourceType: approved.sourceType,
+      version: approved.version,
+      capturedAt: capturedAt(),
+      tenantScope,
+      contentHash: `sha256:${createHash("sha256").update(bytes).digest("hex")}`,
+      metadata: { origin: new URL(url).origin, mediaType: approved.mediaType, byteLength: bytes.length },
+    });
+  } catch {
+    reject("source_rejected");
+  }
+
+  // A read may outlive owner policy or source-version changes. Never return
+  // bytes with a snapshot from a different approved record or revoked grant.
+  let stillPermitted = false;
+  try {
+    stillPermitted = await authorize({ tenantScope, sourceId });
+  } catch {
+    reject("source_access_denied");
+  }
+  if (stillPermitted !== true) reject("source_access_denied");
+  let current;
+  try {
+    current = sources.get(sourceId);
+  } catch {
+    reject("source_not_approved");
+  }
+  if (!unchangedApprovedSource(current, approved, allowedOrigins)) reject("source_not_approved");
+  return { snapshot, bytes };
+}

package/src/engram/store.js

@@ -13,22 +13,218 @@
  *
  * Detachability: imports ONLY the §1 engine core (observations + text) and
  * node builtins. No SentinelLayer session/mcp/auth imports.
+ *
+ * --- On-disk layout (since 2a885ea8) ---
+ *
+ * Each namespace lives under `.sentinelayer/engram/ns-<sha256hex(raw)>/`.
+ * The sha256-hex directory name makes every namespace's storage independent:
+ * distinct namespaces never share a directory, even on case-insensitive
+ * filesystems.  A `namespace.json` sidecar is written on first write and
+ * verified on every subsequent access as defence-in-depth (the stored item
+ * records carry no namespace field, so ownership of a legacy lossy directory
+ * can never be proven from contents alone).
+ *
+ * Before 2a885ea8, namespaceDir mapped a namespace to a lossy sanitized name
+ * (`raw.replace(/[^A-Za-z0-9._-]/g, "_")`), which let distinct namespaces
+ * collide.  The `legacyLossyDirs` option controls what happens when the hashed
+ * directory is absent but the old lossy directory exists:
+ *   - "refuse" (default): throw a typed error, never read or write.
+ *   - "first-claim": atomically rename the legacy dir to the hashed dir, write
+ *     namespace.json with a legacyFrom marker, and proceed.  Two concurrent
+ *     claims yield exactly one owner (rename is the arbiter).
+ *
+ * A `namespace.json` sidecar is written on first write and verified on every
+ * access.  A sidecar whose `raw` names a different namespace causes a
+ * `NamespaceOwnershipError`.
  */
 
 import fsp from "node:fs/promises";
+import crypto from "node:crypto";
 import path from "node:path";
 
 import { buildObservationsFromItems } from "./observations.js";
 import { contentHash, normalizeString } from "../session/recall/text.js";
 
+function sha256hex(str) {
+  return crypto.createHash("sha256").update(str, "utf-8").digest("hex");
+}
+
+const ENGRAM_ROOT = ".sentinelayer";
+const ENGRAM_DIR = "engram";
+
+export class LegacyStorageError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "LegacyStorageError";
+  }
+}
+
+export class NamespaceOwnershipError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "NamespaceOwnershipError";
+  }
+}
+
+/**
+ * The old (pre-2a885ea8) lossy directory name for a namespace.
+ * Exported for legacy migration logic.
+ */
+export function legacyNamespaceDirName(namespace) {
+  return namespace.raw.replace(/[^A-Za-z0-9._-]/g, "_");
+}
+
 /**
- * Where a namespace's files live. EXPORTED so siblings (e.g. build-state.js) resolve
- * the same directory rather than re-deriving the convention -- a second copy of this
- * sanitization would drift and silently point at a different namespace.
+ * Where a namespace's files live.  Each namespace gets its own sha256-hex
+ * directory so distinct namespaces never collide, even on case-insensitive
+ * filesystems.  A `namespace.json` sidecar is written on first write and
+ * verified on every subsequent access.
+ *
+ * EXPORTED so siblings (e.g. build-state.js) resolve the same directory rather
+ * than re-deriving the convention -- a second copy would drift and silently
+ * point at a different namespace.
  */
 export function namespaceDir(root, namespace) {
-  const safe = namespace.raw.replace(/[^A-Za-z0-9._-]/g, "_");
-  return path.join(root, ".sentinelayer", "engram", safe);
+  return path.join(root, ENGRAM_ROOT, ENGRAM_DIR, `ns-${sha256hex(namespace.raw)}`);
+}
+
+/** The old lossy directory path (pre-2a885ea8). */
+function legacyDir(root, namespace) {
+  return path.join(root, ENGRAM_ROOT, ENGRAM_DIR, legacyNamespaceDirName(namespace));
+}
+
+const SIDECAR = "namespace.json";
+
+/**
+ * Verify the directory's namespace.json sidecar matches the expected namespace.
+ * NEVER creates the directory or sidecar.  Throws NamespaceOwnershipError if a
+ * different namespace already owns the directory.
+ */
+export async function verifyNamespace(dir, namespace) {
+  const sidecar = path.join(dir, SIDECAR);
+  let raw;
+  try {
+    raw = await fsp.readFile(sidecar, "utf-8");
+  } catch (e) {
+    if (e && e.code === "ENOENT") {
+      throw new NamespaceOwnershipError(
+        `namespace dir has no sidecar: directory ${dir} is not a valid engram namespace`,
+      );
+    }
+    throw new Error(`corrupt namespace sidecar in ${dir}: ${e.message}`);
+  }
+  let existing;
+  try {
+    existing = JSON.parse(raw);
+  } catch (e) {
+    throw new Error(`corrupt namespace sidecar in ${dir}: ${e.message}`);
+  }
+  if (existing && typeof existing === "object" && existing !== null) {
+    if (existing.raw !== namespace.raw) {
+      throw new NamespaceOwnershipError(
+        `namespace dir collision: directory ${dir} already owned by "${existing.raw}" (tried to access as "${namespace.raw}")`,
+      );
+    }
+    return;
+  }
+  throw new Error(`corrupt namespace sidecar in ${dir}: expected object, got ${typeof existing}`);
+}
+
+/**
+ * Ensure the directory's namespace.json sidecar matches the expected namespace,
+ * writing it on first write with flag "wx" so a concurrent create is detected.
+ * Throws NamespaceOwnershipError if a different namespace already owns the
+ * directory.
+ */
+export async function ensureNamespace(dir, namespace, legacyFrom) {
+  await fsp.mkdir(dir, { recursive: true });
+  const sidecar = path.join(dir, SIDECAR);
+  try {
+    await fsp.writeFile(
+      sidecar,
+      JSON.stringify({ raw: namespace.raw, ...(legacyFrom ? { legacyFrom } : {}) }, null, 2) + "\n",
+      { flag: "wx" },
+    );
+    return;
+  } catch (e) {
+    if (e && e.code === "EEXIST") {
+      // Sidecar already exists — verify it matches.
+      return verifyNamespace(dir, namespace);
+    }
+    throw e;
+  }
+}
+
+/**
+ * Resolve the namespace directory, handling legacy migration if configured.
+ * Returns the directory path to use.
+ */
+export async function resolveNamespaceDir(root, namespace, legacyLossyDirs) {
+  const dir = namespaceDir(root, namespace);
+  try {
+    await fsp.access(dir);
+    return dir;
+  } catch {
+    // Hashed dir doesn't exist — check for legacy
+  }
+
+  const oldDir = legacyDir(root, namespace);
+  let legacyExists = false;
+  try {
+    await fsp.access(oldDir);
+    legacyExists = true;
+  } catch {
+    // No legacy dir either
+  }
+
+  if (!legacyExists) {
+    return dir;
+  }
+
+  if (legacyLossyDirs === "first-claim") {
+    // Atomically claim the legacy directory via rename
+    try {
+      await fsp.rename(oldDir, dir);
+      // Write sidecar with legacy marker
+      await ensureNamespace(dir, namespace, legacyNamespaceDirName(namespace));
+      // Notify once per claim
+      console.error(
+        `engram: claimed legacy storage for "${namespace.raw}" from lossy dir "${legacyNamespaceDirName(namespace)}"`,
+      );
+      return dir;
+    } catch (e) {
+      if (e && e.code === "ENOENT") {
+        // Lost the race — another caller claimed it or it was deleted.
+        // Try the hashed dir now (the winner may have renamed to it).
+        try {
+          await fsp.access(dir);
+          return dir;
+        } catch {
+          // Neither exists — start fresh
+          return dir;
+        }
+      }
+      // NS6: on EEXIST/ENOTEMPTY/EPERM, the hashed dir appeared concurrently.
+      // Re-check: if its sidecar is ours, use it; otherwise rethrow.
+      if (e && (e.code === "EEXIST" || e.code === "ENOTEMPTY" || e.code === "EPERM")) {
+        try {
+          await verifyNamespace(dir, namespace);
+          // Sidecar is ours — use the hashed dir, leave legacy untouched
+          return dir;
+        } catch {
+          // Sidecar names another namespace — rethrow original
+        }
+      }
+      throw e;
+    }
+  }
+
+  // "refuse" — the default
+  // Note: the error message intentionally omits directory paths (public repo).
+  throw new LegacyStorageError(
+    `ambiguous legacy storage for namespace "${namespace.raw}". The old lossy directory still exists. ` +
+    `Run with legacyLossyDirs: "first-claim" to migrate, or delete the legacy dir manually.`,
+  );
 }
 
 /** Stable, content-addressed item id (idempotent write — §3 dedup for free). */
@@ -66,17 +262,20 @@ async function readItemsFile(file) {
  * @param {string} options.storeRoot          Root dir for the append-log store.
  * @param {Record<string, (id:string)=>Promise<object[]>>} [options.adapters]
  *        Map of namespace-kind -> async source adapter returning observations.
+ * @param {"refuse"|"first-claim"} [options.legacyLossyDirs="refuse"]
+ *        Policy for pre-2a885ea8 lossy directories.
  * @returns {{
  *   appendItems: (namespace:object, items:object[]) => Promise<{written:number, deduped:number, namespace:string}>,
  *   readObservations: (namespace:object) => Promise<object[]>,
  * }}
  */
-export function createStore({ storeRoot, adapters = {} } = {}) {
+export function createStore({ storeRoot, adapters = {}, legacyLossyDirs = "refuse" } = {}) {
   const root = path.resolve(String(storeRoot || "."));
 
   return {
     async appendItems(namespace, items = []) {
-      const dir = namespaceDir(root, namespace);
+      const dir = await resolveNamespaceDir(root, namespace, legacyLossyDirs);
+      await ensureNamespace(dir, namespace);
       const file = path.join(dir, "items.ndjson");
       const existing = await readItemsFile(file);
       const seen = new Set(existing.map((it) => itemId(it)));
@@ -105,8 +304,27 @@ export function createStore({ storeRoot, adapters = {} } = {}) {
       const adapterObservations = adapter
         ? await Promise.resolve(adapter(namespace.id)).catch(() => [])
         : [];
-      const file = path.join(namespaceDir(root, namespace), "items.ndjson");
-      const items = await readItemsFile(file);
+      const dir = await resolveNamespaceDir(root, namespace, legacyLossyDirs);
+      // NS1: reads never create.  If the hashed dir is absent, return empty.
+      let dirExists = false;
+      try {
+        await fsp.access(dir);
+        dirExists = true;
+      } catch {
+        // dir absent — no data
+      }
+
+      let items = [];
+      if (dirExists) {
+        // A first-claim rename on read is allowed (the explicit migration policy
+        // in resolveNamespaceDir handles it).  If the dir exists after
+        // resolution, verify its sidecar without creating anything.
+        await verifyNamespace(dir, namespace);
+        const file = path.join(dir, "items.ndjson");
+        items = await readItemsFile(file);
+      }
+      // If dir is absent and no adapter observations, items stays []
+      // and the union below produces only adapter observations (or []).
       const itemObservations = buildObservationsFromItems(items, { namespace: namespace.raw }).observations;
 
       // Union, dedup by id (first wins — adapter source is authoritative for its ids).

package/src/ingest/engine.js

@@ -1,3 +1,4 @@
+import { requireOutputFileSystem } from "../config/output-filesystem.js";
 import { execFile } from "node:child_process";
 import { createHash } from "node:crypto";
 import fs from "node:fs";
@@ -8,7 +9,7 @@ import { promisify } from "node:util";
 
 import ignore from "ignore";
 
-import { resolveOutputRoot } from "../config/service.js";
+import { resolveOutputContext } from "../config/service.js";
 
 const DEFAULT_IGNORED_DIRS = new Set([
   ".git",
@@ -259,19 +260,6 @@ async function readExistingIngest(outputPath) {
   }
 }
 
-async function resolveIngestOutputPath({ rootPath, outputFile = "", outputDir = "" }) {
-  const resolvedRoot = path.resolve(rootPath || process.cwd());
-  const explicitOutputFile = String(outputFile || "").trim();
-  if (explicitOutputFile) {
-    return path.resolve(resolvedRoot, explicitOutputFile);
-  }
-  const outputRoot = await resolveOutputRoot({
-    cwd: resolvedRoot,
-    outputDirOverride: outputDir,
-  });
-  return path.join(outputRoot, "CODEBASE_INGEST.json");
-}
-
 async function readGitLastCommitAt(rootPath) {
   const resolvedRoot = path.resolve(rootPath || process.cwd());
   try {
@@ -793,36 +781,36 @@ export function formatIngestSummary(ingest) {
   return lines.join("\n");
 }
 
-export async function writeCodebaseIngest({ ingest, rootPath, outputFile = "", outputDir = "" } = {}) {
+async function resolveIngestOutputContext({ rootPath, outputFile = "", outputDir = "" }) {
   const resolvedRoot = path.resolve(rootPath || process.cwd());
   const resolvedOutputFile = String(outputFile || "").trim();
-  const outputPath = resolvedOutputFile
-    ? path.resolve(resolvedRoot, resolvedOutputFile)
-    : path.join(
-        await resolveOutputRoot({
-          cwd: resolvedRoot,
-          outputDirOverride: outputDir,
-        }),
-        "CODEBASE_INGEST.json"
-      );
-
-  await fsp.mkdir(path.dirname(outputPath), { recursive: true });
-  await fsp.writeFile(outputPath, `${JSON.stringify(ingest, null, 2)}\n`, "utf-8");
+  const output = await resolveOutputContext({ cwd: resolvedRoot, outputDirOverride: resolvedOutputFile || outputDir });
+  return { outputPath: resolvedOutputFile ? output.outputRoot : path.join(output.outputRoot, "CODEBASE_INGEST.json"), outputFs: output.outputFs };
+}
+
+export async function writeCodebaseIngest({ ingest, rootPath, outputFile = "", outputDir = "", outputFs } = {}) {
+  requireOutputFileSystem(outputFs);
+  const { outputPath } = await resolveIngestOutputContext({ rootPath, outputFile, outputDir });
+
+  await outputFs.mkdir(path.dirname(outputPath), { recursive: true });
+  await outputFs.writeFile(outputPath, `${JSON.stringify(ingest, null, 2)}\n`, "utf-8");
   return outputPath;
 }
 
 export async function resolveCodebaseIngest({
+  outputFs: inheritedOutputFs,
   rootPath = process.cwd(),
   outputFile = "",
   outputDir = "",
   refresh = false,
 } = {}) {
   const resolvedRoot = path.resolve(rootPath || process.cwd());
-  const outputPath = await resolveIngestOutputPath({
+  const { outputPath, outputFs: resolvedOutputFs } = await resolveIngestOutputContext({
     rootPath: resolvedRoot,
     outputFile,
     outputDir,
   });
+  const outputFs = inheritedOutputFs === undefined ? resolvedOutputFs : requireOutputFileSystem(inheritedOutputFs);
   const existingIngest = await readExistingIngest(outputPath);
   const fingerprint = await computeCodebaseContentFingerprint({
     rootPath: resolvedRoot,
@@ -859,6 +847,7 @@ export async function resolveCodebaseIngest({
     ingest.cache.filesCount = fingerprint.filesCount;
     ingest.cache.latestFileMtimeMs = fingerprint.latestFileMtimeMs;
     await writeCodebaseIngest({
+      outputFs,
       ingest,
       rootPath: resolvedRoot,
       outputFile,
@@ -900,12 +889,16 @@ export async function resolveCodebaseIngest({
 }
 
 export async function generateCodebaseIngest({
+  outputFs: inheritedOutputFs,
   rootPath = process.cwd(),
   outputFile = "",
   outputDir = "",
 } = {}) {
+  const { outputFs: resolvedOutputFs } = await resolveIngestOutputContext({ rootPath, outputFile, outputDir });
+  const outputFs = inheritedOutputFs === undefined ? resolvedOutputFs : requireOutputFileSystem(inheritedOutputFs);
   const ingest = await collectCodebaseIngest({ rootPath });
   const outputPath = await writeCodebaseIngest({
+    outputFs,
     ingest,
     rootPath,
     outputFile,