@vellumai/assistant 0.7.1 → 0.7.3

package/src/runtime/migrations/__tests__/vbundle-import-parity.test.ts

@@ -0,0 +1,413 @@
+/**
+ * Buffer-vs-streaming `.vbundle` import parity suite.
+ *
+ * Pins the existing disk-outcome equivalence between `commitImport`
+ * (buffer-based) and `streamCommitImport` (streaming) as a regression net
+ * BEFORE any production code is migrated to a shared policy module.
+ *
+ * Each test builds one archive, mkdtemps two sibling workspaces, seeds them
+ * identically, runs each importer against its own workspace, and asserts the
+ * post-import disk trees are byte-for-byte identical:
+ *
+ *   expect(walkDiskTree(streamWs)).toEqual(walkDiskTree(bufferWs))
+ *
+ * Per-case invariants (carry-forward markers survive, persona lands at the
+ * right disk path, traversal entries do not erase the workspace, etc.) are
+ * asserted on top of disk-tree equality.
+ */
+
+import { createHash } from "node:crypto";
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  readFileSync,
+  realpathSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, relative } from "node:path";
+import { Readable } from "node:stream";
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+
+import { buildVBundle } from "../vbundle-builder.js";
+import { DefaultPathResolver } from "../vbundle-import-analyzer.js";
+import { commitImport } from "../vbundle-importer.js";
+import { streamCommitImport } from "../vbundle-streaming-importer.js";
+import { defaultV1Options } from "./v1-test-helpers.js";
+
+// ---------------------------------------------------------------------------
+// Shared helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Allocate a fresh workspace path under a temp parent dir we own. The parent
+ * is realpath-resolved so macOS `/var` → `/private/var` symlink mismatches
+ * don't trip the streaming importer's `rebaseOntoTempWorkspace` containment
+ * check (which compares `resolve(diskPath)` against `resolve(workspaceDir)`).
+ *
+ * Returns `<parent>/workspace`. The directory itself is NOT created — tests
+ * that need it pre-existing call `mkdirSync` themselves.
+ */
+function freshWorkspace(): string {
+  const parent = realpathSync(
+    mkdtempSync(join(tmpdir(), "vbundle-import-parity-")),
+  );
+  return join(parent, "workspace");
+}
+
+/** Best-effort cleanup of a workspace's parent dir. */
+function cleanupWorkspaceParent(workspaceDir: string): void {
+  try {
+    rmSync(join(workspaceDir, ".."), { recursive: true, force: true });
+  } catch {
+    // best-effort
+  }
+}
+
+function sha256Hex(data: Uint8Array): string {
+  return createHash("sha256").update(data).digest("hex");
+}
+
+/**
+ * Recursively walk `root` and return a `Map<relPath, sha256Hex>` for every
+ * regular file. Skips dot-prefixed scratch dirs the streaming importer may
+ * leave behind on failure paths (`.import-*`, `.pre-import-*`) plus the
+ * import marker file — the buffer importer never produces these, so they'd
+ * spuriously break parity if included.
+ *
+ * Two importers are parity-equivalent for a given input iff the maps they
+ * produce on identically-seeded sibling workspaces are equal.
+ */
+function walkDiskTree(root: string): Map<string, string> {
+  const out = new Map<string, string>();
+  if (!existsSync(root)) return out;
+
+  const stack: string[] = [root];
+  while (stack.length > 0) {
+    const dir = stack.pop()!;
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      // Skip streaming-importer scratch artifacts so they don't show up as
+      // false negatives in the parity comparison.
+      if (
+        entry.name.startsWith(".import-") ||
+        entry.name.startsWith(".pre-import-") ||
+        entry.name === ".import-marker.json"
+      ) {
+        continue;
+      }
+      const abs = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(abs);
+      } else if (entry.isFile()) {
+        const rel = relative(root, abs);
+        out.set(rel, sha256Hex(readFileSync(abs)));
+      }
+    }
+  }
+  return out;
+}
+
+interface SeedFile {
+  relPath: string;
+  content: string | Uint8Array;
+}
+
+/** Mkdir parents and write each file to `workspaceDir`. */
+function seedLiveWorkspace(workspaceDir: string, files: SeedFile[]): void {
+  mkdirSync(workspaceDir, { recursive: true });
+  for (const { relPath, content } of files) {
+    const abs = join(workspaceDir, relPath);
+    mkdirSync(dirname(abs), { recursive: true });
+    writeFileSync(abs, content);
+  }
+}
+
+function runBufferImport(workspaceDir: string, archive: Uint8Array): void {
+  const result = commitImport({
+    archiveData: archive,
+    pathResolver: new DefaultPathResolver(workspaceDir),
+    workspaceDir,
+  });
+  if (!result.ok) {
+    throw new Error(
+      `buffer commitImport unexpectedly failed: ${JSON.stringify(result)}`,
+    );
+  }
+}
+
+async function runStreamImport(
+  workspaceDir: string,
+  archive: Uint8Array,
+  importCredentials?: (
+    credentials: Array<{ account: string; value: string }>,
+  ) => Promise<void>,
+): Promise<void> {
+  const result = await streamCommitImport({
+    source: Readable.from([Buffer.from(archive)]),
+    pathResolver: new DefaultPathResolver(workspaceDir),
+    workspaceDir,
+    importCredentials,
+  });
+  if (!result.ok) {
+    throw new Error(
+      `streamCommitImport unexpectedly failed: ${JSON.stringify(result)}`,
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Parity tests
+// ---------------------------------------------------------------------------
+
+describe("vbundle import parity (buffer vs streaming)", () => {
+  let bufferWs: string;
+  let streamWs: string;
+
+  beforeEach(() => {
+    bufferWs = freshWorkspace();
+    streamWs = freshWorkspace();
+  });
+
+  afterEach(() => {
+    cleanupWorkspaceParent(bufferWs);
+    cleanupWorkspaceParent(streamWs);
+  });
+
+  test("A — full workspace + credentials: identical disk outcome", async () => {
+    const dbBytes = new Uint8Array(16);
+    for (let i = 0; i < dbBytes.length; i++) dbBytes[i] = (i * 17) & 0xff;
+
+    const configJson = JSON.stringify({ version: 1 });
+    const metadataJson = JSON.stringify({
+      version: 5,
+      credentials: [
+        {
+          credentialId: "id-openai-api_key",
+          service: "openai",
+          field: "api_key",
+          allowedTools: [],
+          allowedDomains: [],
+          createdAt: 1700000000000,
+          updatedAt: 1700000000000,
+        },
+      ],
+    });
+
+    const openaiKey = new Uint8Array(16);
+    for (let i = 0; i < openaiKey.length; i++) openaiKey[i] = (i + 5) & 0xff;
+    const anthropicKey = new TextEncoder().encode("sk-ant-test");
+
+    const { archive } = buildVBundle({
+      files: [
+        { path: "workspace/data/db/assistant.db", data: dbBytes },
+        {
+          path: "workspace/config.json",
+          data: new TextEncoder().encode(configJson),
+        },
+        {
+          path: "workspace/data/credentials/metadata.json",
+          data: new TextEncoder().encode(metadataJson),
+        },
+        { path: "credentials/openai-key", data: openaiKey },
+        { path: "credentials/anthropic-key", data: anthropicKey },
+      ],
+      ...defaultV1Options(),
+    });
+
+    // Pre-create both workspaces (streaming importer expects to operate
+    // against an existing dir and the atomic-swap path requires it).
+    mkdirSync(bufferWs, { recursive: true });
+    mkdirSync(streamWs, { recursive: true });
+
+    runBufferImport(bufferWs, archive);
+    await runStreamImport(streamWs, archive, async () => {
+      // parity test: credentials are intercepted but not persisted
+    });
+
+    const bufferMap = walkDiskTree(bufferWs);
+    const streamMap = walkDiskTree(streamWs);
+
+    expect(streamMap).toEqual(bufferMap);
+
+    // Sanity: the three workspace-bound files we expect both importers to
+    // land are present in the parity map.
+    expect(bufferMap.has("data/db/assistant.db")).toBe(true);
+    expect(bufferMap.has("config.json")).toBe(true);
+    expect(bufferMap.has("data/credentials/metadata.json")).toBe(true);
+  });
+
+  test("B — config-only partial bundle: live preserved paths survive on both sides", async () => {
+    const seeds: SeedFile[] = [
+      { relPath: "data/db/marker", content: "db-marker" },
+      { relPath: "data/qdrant/marker", content: "qdrant-marker" },
+      { relPath: "embedding-models/marker", content: "embedding-marker" },
+      { relPath: "deprecated/marker", content: "deprecated-marker" },
+    ];
+
+    seedLiveWorkspace(bufferWs, seeds);
+    seedLiveWorkspace(streamWs, seeds);
+
+    const configJson = JSON.stringify({ version: 1 });
+    const { archive } = buildVBundle({
+      files: [
+        // Validator requires the DB entry (legacy or workspace-prefixed).
+        // It's not the focus of this case — config.json is — but it must
+        // be present for the bundle to validate.
+        { path: "data/db/assistant.db", data: new Uint8Array() },
+        {
+          path: "workspace/config.json",
+          data: new TextEncoder().encode(configJson),
+        },
+      ],
+      ...defaultV1Options(),
+    });
+
+    runBufferImport(bufferWs, archive);
+    await runStreamImport(streamWs, archive);
+
+    const bufferMap = walkDiskTree(bufferWs);
+    const streamMap = walkDiskTree(streamWs);
+
+    expect(streamMap).toEqual(bufferMap);
+
+    // Each carry-forward marker must still be on disk.
+    for (const seed of seeds) {
+      expect(bufferMap.has(seed.relPath)).toBe(true);
+      expect(streamMap.has(seed.relPath)).toBe(true);
+    }
+  });
+
+  test("C — legacy prompts/USER.md: both importers land it at users/<slug>.md", async () => {
+    const personaBody = `_ Lines starting with _ are comments - they won't appear in the system prompt
+
+# User Profile
+
+- Preferred name/reference: Captain Parity
+- Pronouns: they/them
+- Locale: en-US
+- Work role: Quartermaster
+- Goals: Verify importer parity
+- Hobbies/fun: Diff'ing trees
+- Daily tools: Terminal
+`;
+
+    // Pre-create users/ in both workspaces so the resolver's containment
+    // check has a real on-disk parent to anchor against.
+    mkdirSync(join(bufferWs, "users"), { recursive: true });
+    mkdirSync(join(streamWs, "users"), { recursive: true });
+
+    const { archive } = buildVBundle({
+      files: [
+        { path: "data/db/assistant.db", data: new Uint8Array() },
+        {
+          path: "prompts/USER.md",
+          data: new TextEncoder().encode(personaBody),
+        },
+      ],
+      ...defaultV1Options(),
+    });
+
+    const bufferGuardianPath = join(bufferWs, "users", "captain.md");
+    const streamGuardianPath = join(streamWs, "users", "captain.md");
+
+    const bufferResolver = new DefaultPathResolver(
+      bufferWs,
+      undefined,
+      () => bufferGuardianPath,
+    );
+    const streamResolver = new DefaultPathResolver(
+      streamWs,
+      undefined,
+      () => streamGuardianPath,
+    );
+
+    const bufferResult = commitImport({
+      archiveData: archive,
+      pathResolver: bufferResolver,
+      workspaceDir: bufferWs,
+    });
+    expect(bufferResult.ok).toBe(true);
+
+    const streamResult = await streamCommitImport({
+      source: Readable.from([Buffer.from(archive)]),
+      pathResolver: streamResolver,
+      workspaceDir: streamWs,
+    });
+    expect(streamResult.ok).toBe(true);
+
+    const bufferMap = walkDiskTree(bufferWs);
+    const streamMap = walkDiskTree(streamWs);
+
+    expect(streamMap).toEqual(bufferMap);
+
+    expect(existsSync(bufferGuardianPath)).toBe(true);
+    expect(existsSync(streamGuardianPath)).toBe(true);
+    expect(readFileSync(bufferGuardianPath, "utf-8")).toBe(personaBody);
+    expect(readFileSync(streamGuardianPath, "utf-8")).toBe(personaBody);
+  });
+
+  test("D — no workspace entries at all: legacy bundle leaves seeded files in place", async () => {
+    const seeds: SeedFile[] = [
+      { relPath: "unrelated.txt", content: "stay" },
+      { relPath: "custom-dir/note.md", content: "# note" },
+    ];
+
+    seedLiveWorkspace(bufferWs, seeds);
+    seedLiveWorkspace(streamWs, seeds);
+
+    const dbBytes = new TextEncoder().encode("legacy-db-payload");
+    const { archive } = buildVBundle({
+      files: [{ path: "data/db/assistant.db", data: dbBytes }],
+      ...defaultV1Options(),
+    });
+
+    runBufferImport(bufferWs, archive);
+    await runStreamImport(streamWs, archive);
+
+    const bufferMap = walkDiskTree(bufferWs);
+    const streamMap = walkDiskTree(streamWs);
+
+    expect(streamMap).toEqual(bufferMap);
+
+    for (const seed of seeds) {
+      expect(bufferMap.has(seed.relPath)).toBe(true);
+      expect(streamMap.has(seed.relPath)).toBe(true);
+    }
+  });
+
+  test("E — path-traversal workspace entry: both importers refuse to clear", async () => {
+    seedLiveWorkspace(bufferWs, [{ relPath: "marker.txt", content: "keep" }]);
+    seedLiveWorkspace(streamWs, [{ relPath: "marker.txt", content: "keep" }]);
+
+    const { archive } = buildVBundle({
+      files: [
+        { path: "data/db/assistant.db", data: new Uint8Array() },
+        {
+          path: "workspace/../../etc/passwd",
+          data: new TextEncoder().encode("nope"),
+        },
+      ],
+      ...defaultV1Options(),
+    });
+
+    runBufferImport(bufferWs, archive);
+    await runStreamImport(streamWs, archive);
+
+    const bufferMap = walkDiskTree(bufferWs);
+    const streamMap = walkDiskTree(streamWs);
+
+    expect(streamMap).toEqual(bufferMap);
+
+    expect(bufferMap.has("marker.txt")).toBe(true);
+    expect(streamMap.has("marker.txt")).toBe(true);
+  });
+});

package/src/runtime/migrations/__tests__/vbundle-import-policy.test.ts

@@ -0,0 +1,260 @@
+/**
+ * Unit tests for the pure policy module shared by both vbundle importers.
+ *
+ * No `node:fs`, no temp dirs — every test exercises a constant or a
+ * predicate over strings.
+ */
+
+import { describe, expect, test } from "bun:test";
+
+import {
+  compareSemver,
+  CONFIG_ARCHIVE_PATHS,
+  CREDENTIAL_METADATA_ARCHIVE_PATH,
+  evaluateRuntimeCompatibility,
+  isConfigArchivePath,
+  isCredentialMetadataArchivePath,
+  isLegacyPersonaArchivePath,
+  isWorkspaceNamespacedArchivePath,
+  LEGACY_USER_MD_ARCHIVE_PATH,
+  partitionWorkspacePreserveSkipDirs,
+  WORKSPACE_PRESERVE_PATHS,
+} from "../vbundle-import-policy.js";
+
+describe("LEGACY_USER_MD_ARCHIVE_PATH", () => {
+  test("equals the legacy guardian persona archive path", () => {
+    expect(LEGACY_USER_MD_ARCHIVE_PATH).toBe("prompts/USER.md");
+  });
+});
+
+describe("CONFIG_ARCHIVE_PATHS", () => {
+  test("contains exactly the two known config archive paths", () => {
+    expect(CONFIG_ARCHIVE_PATHS.size).toBe(2);
+    expect(CONFIG_ARCHIVE_PATHS.has("workspace/config.json")).toBe(true);
+    expect(CONFIG_ARCHIVE_PATHS.has("config/settings.json")).toBe(true);
+  });
+});
+
+describe("CREDENTIAL_METADATA_ARCHIVE_PATH", () => {
+  test("equals the workspace-namespaced credential metadata path", () => {
+    expect(CREDENTIAL_METADATA_ARCHIVE_PATH).toBe(
+      "workspace/data/credentials/metadata.json",
+    );
+  });
+});
+
+describe("WORKSPACE_PRESERVE_PATHS", () => {
+  test("matches the literal 4-element ordered list", () => {
+    expect(WORKSPACE_PRESERVE_PATHS).toEqual([
+      "embedding-models",
+      "deprecated",
+      "data/db",
+      "data/qdrant",
+    ]);
+  });
+});
+
+describe("isWorkspaceNamespacedArchivePath", () => {
+  test("true for paths under workspace/", () => {
+    expect(isWorkspaceNamespacedArchivePath("workspace/foo")).toBe(true);
+    expect(isWorkspaceNamespacedArchivePath("workspace/data/db/x")).toBe(true);
+  });
+
+  test("false for non-workspace paths", () => {
+    expect(isWorkspaceNamespacedArchivePath("prompts/USER.md")).toBe(false);
+    expect(isWorkspaceNamespacedArchivePath("data/db/assistant.db")).toBe(
+      false,
+    );
+    expect(isWorkspaceNamespacedArchivePath("")).toBe(false);
+    expect(isWorkspaceNamespacedArchivePath("workspace")).toBe(false);
+  });
+});
+
+describe("isLegacyPersonaArchivePath", () => {
+  test("true only for the exact legacy path", () => {
+    expect(isLegacyPersonaArchivePath("prompts/USER.md")).toBe(true);
+  });
+
+  test("false for near-misses and unrelated paths", () => {
+    expect(isLegacyPersonaArchivePath("prompts/USER")).toBe(false);
+    expect(isLegacyPersonaArchivePath("workspace/prompts/USER.md")).toBe(false);
+    expect(isLegacyPersonaArchivePath("")).toBe(false);
+  });
+});
+
+describe("isConfigArchivePath", () => {
+  test("true for both members of CONFIG_ARCHIVE_PATHS", () => {
+    expect(isConfigArchivePath("workspace/config.json")).toBe(true);
+    expect(isConfigArchivePath("config/settings.json")).toBe(true);
+  });
+
+  test("false for non-members", () => {
+    expect(isConfigArchivePath("workspace/foo.json")).toBe(false);
+    expect(isConfigArchivePath("config/settings")).toBe(false);
+    expect(isConfigArchivePath("")).toBe(false);
+  });
+});
+
+describe("isCredentialMetadataArchivePath", () => {
+  test("true for the exact constant", () => {
+    expect(
+      isCredentialMetadataArchivePath(
+        "workspace/data/credentials/metadata.json",
+      ),
+    ).toBe(true);
+  });
+
+  test("false for the legacy non-prefixed form and empty string", () => {
+    expect(
+      isCredentialMetadataArchivePath("data/credentials/metadata.json"),
+    ).toBe(false);
+    expect(isCredentialMetadataArchivePath("")).toBe(false);
+  });
+});
+
+describe("partitionWorkspacePreserveSkipDirs", () => {
+  test("splits preserve-paths into top-level vs data-subdir skip sets", () => {
+    const { topLevelSkipDirs, dataSubdirSkipDirs } =
+      partitionWorkspacePreserveSkipDirs();
+
+    expect(topLevelSkipDirs.size).toBe(2);
+    expect(topLevelSkipDirs.has("embedding-models")).toBe(true);
+    expect(topLevelSkipDirs.has("deprecated")).toBe(true);
+
+    expect(dataSubdirSkipDirs.size).toBe(2);
+    expect(dataSubdirSkipDirs.has("db")).toBe(true);
+    expect(dataSubdirSkipDirs.has("qdrant")).toBe(true);
+  });
+});
+
+describe("compareSemver", () => {
+  test("0.10.0 > 0.9.0 (numeric, not lexical)", () => {
+    expect(compareSemver("0.10.0", "0.9.0")).toBe(1);
+  });
+
+  test("equal triples return 0", () => {
+    expect(compareSemver("0.7.1", "0.7.1")).toBe(0);
+  });
+
+  test("smaller patch returns -1", () => {
+    expect(compareSemver("0.7.0", "0.7.1")).toBe(-1);
+  });
+
+  test("prerelease tag is stripped (treated as base release)", () => {
+    expect(compareSemver("0.7.1-staging.1", "0.7.1")).toBe(0);
+  });
+
+  test("non-version string returns null", () => {
+    expect(compareSemver("not-a-version", "0.7.1")).toBe(null);
+  });
+
+  test("two-part version returns null", () => {
+    expect(compareSemver("1.2", "0.7.1")).toBe(null);
+  });
+
+  // Regression: Number.parseInt accepts numeric prefixes and ignores
+  // trailing junk ("0foo" → 0), which previously coerced malformed
+  // triples through the gate. parseSemverTriple now requires each
+  // component to match /^\d+$/ exactly.
+  test("trailing junk on a component returns null (left arg)", () => {
+    expect(compareSemver("0.8.0foo", "0.8.0")).toBe(null);
+  });
+
+  test("trailing junk on a component returns null (right arg)", () => {
+    expect(compareSemver("0.8.0", "0.7.1xyz")).toBe(null);
+  });
+
+  // Leading zeros are accepted: "01.02.03" parses to the same numeric
+  // triple as "1.2.3" since Number("01") === 1. We pin this behavior
+  // so a future tightening doesn't accidentally regress callers that
+  // pass zero-padded versions from upstream tooling.
+  test("leading zeros parse equal to un-padded triple", () => {
+    expect(compareSemver("01.02.03", "1.2.3")).toBe(0);
+  });
+
+  test("leading whitespace returns null", () => {
+    expect(compareSemver(" 0.8.0", "0.8.0")).toBe(null);
+  });
+
+  test("negative component returns null", () => {
+    expect(compareSemver("0.8.-1", "0.8.0")).toBe(null);
+  });
+});
+
+describe("evaluateRuntimeCompatibility", () => {
+  test("legacy sentinel passes regardless of runtime version", () => {
+    expect(
+      evaluateRuntimeCompatibility(
+        { min_runtime_version: "0.0.0-legacy", max_runtime_version: null },
+        "0.7.1",
+      ),
+    ).toEqual({ ok: true });
+  });
+
+  test("runtime above min with no max passes", () => {
+    expect(
+      evaluateRuntimeCompatibility(
+        { min_runtime_version: "0.7.0", max_runtime_version: null },
+        "0.7.1",
+      ),
+    ).toEqual({ ok: true });
+  });
+
+  test("runtime below min fails with full echo", () => {
+    const compat = {
+      min_runtime_version: "0.8.0",
+      max_runtime_version: null,
+    };
+    expect(evaluateRuntimeCompatibility(compat, "0.7.1")).toEqual({
+      ok: false,
+      reason: "version_incompatible",
+      bundle_compat: compat,
+      runtime_version: "0.7.1",
+    });
+  });
+
+  test("runtime above max fails", () => {
+    const compat = {
+      min_runtime_version: "0.7.0",
+      max_runtime_version: "0.7.5",
+    };
+    expect(evaluateRuntimeCompatibility(compat, "0.8.0")).toEqual({
+      ok: false,
+      reason: "version_incompatible",
+      bundle_compat: compat,
+      runtime_version: "0.8.0",
+    });
+  });
+
+  test("max is inclusive", () => {
+    expect(
+      evaluateRuntimeCompatibility(
+        { min_runtime_version: "0.7.0", max_runtime_version: "0.7.5" },
+        "0.7.5",
+      ),
+    ).toEqual({ ok: true });
+  });
+
+  test("unparsable min skips the gate (fail-open)", () => {
+    expect(
+      evaluateRuntimeCompatibility(
+        { min_runtime_version: "garbage", max_runtime_version: null },
+        "0.7.1",
+      ),
+    ).toEqual({ ok: true });
+  });
+
+  // Regression for Codex feedback: a malformed min like "0.8.0foo"
+  // previously coerced to [0, 8, 0] via Number.parseInt and incorrectly
+  // produced a version_incompatible decision against runtime "0.7.1".
+  // With strict per-component digit matching, the parse fails and the
+  // gate fails open.
+  test("malformed min with trailing junk fails open, does not block", () => {
+    expect(
+      evaluateRuntimeCompatibility(
+        { min_runtime_version: "0.8.0foo", max_runtime_version: null },
+        "0.7.1",
+      ),
+    ).toEqual({ ok: true });
+  });
+});