@xenonbyte/da-vinci-workflow 0.2.2 → 0.2.3

package/lib/save-current-design.js

@@ -0,0 +1,790 @@
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const {
+  DEFAULT_READ_DEPTH,
+  normalizeNodesPayload,
+  normalizeVariablesPayload,
+  readPenDocument,
+  runPencilInteractive,
+  extractFirstJson
+} = require("./pen-persistence");
+const { readSessionState, persistPencilSession } = require("./pencil-session");
+const { getPencilLockStatus, isStaleLock } = require("./pencil-lock");
+const {
+  resolvePreferredRegisteredPenPath,
+  normalizeRegisteredPenPath,
+  normalizeSessionPenPath,
+  normalizeActiveEditorPath
+} = require("./design-source-registry");
+const { readTextIfExists } = require("./utils");
+
+const SAVE_STATUS = Object.freeze({
+  SAVED: "saved",
+  BLOCKED: "blocked",
+  UNAVAILABLE: "unavailable"
+});
+
+const SAVE_CODES = Object.freeze({
+  SAVE_COMPLETED: "SAVE_COMPLETED",
+  REGISTERED_PEN_MISSING: "REGISTERED_PEN_MISSING",
+  REGISTERED_PEN_INVALID: "REGISTERED_PEN_INVALID",
+  SESSION_STATE_MISSING: "SESSION_STATE_MISSING",
+  SESSION_STATE_INVALID: "SESSION_STATE_INVALID",
+  SESSION_NOT_ACTIVE: "SESSION_NOT_ACTIVE",
+  SESSION_PEN_MISSING: "SESSION_PEN_MISSING",
+  SESSION_PEN_INVALID: "SESSION_PEN_INVALID",
+  ACTIVE_EDITOR_MISSING: "ACTIVE_EDITOR_MISSING",
+  ACTIVE_EDITOR_NEW: "ACTIVE_EDITOR_NEW",
+  ACTIVE_EDITOR_INVALID: "ACTIVE_EDITOR_INVALID",
+  BOUND_SOURCE_MISMATCH: "BOUND_SOURCE_MISMATCH",
+  LOCK_MISSING: "LOCK_MISSING",
+  LOCK_INVALID: "LOCK_INVALID",
+  LOCK_STALE: "LOCK_STALE",
+  LOCK_OWNED_BY_OTHER_PROJECT: "LOCK_OWNED_BY_OTHER_PROJECT",
+  BOUND_PEN_MISSING: "BOUND_PEN_MISSING",
+  BOUND_PEN_VERSION_UNREADABLE: "BOUND_PEN_VERSION_UNREADABLE",
+  SNAPSHOT_NODES_TRUNCATED: "SNAPSHOT_NODES_TRUNCATED",
+  SNAPSHOT_NODES_INVALID: "SNAPSHOT_NODES_INVALID",
+  SNAPSHOT_VARIABLES_INVALID: "SNAPSHOT_VARIABLES_INVALID",
+  ACTIVE_EDITOR_DRIFT: "ACTIVE_EDITOR_DRIFT",
+  PERSIST_FAILED: "PERSIST_FAILED",
+  PERSIST_NOT_IN_SYNC: "PERSIST_NOT_IN_SYNC",
+  MCP_BRIDGE_UNAVAILABLE: "MCP_BRIDGE_UNAVAILABLE",
+  MCP_EDITOR_STATE_UNAVAILABLE: "MCP_EDITOR_STATE_UNAVAILABLE",
+  MCP_SNAPSHOT_UNAVAILABLE: "MCP_SNAPSHOT_UNAVAILABLE"
+});
+
+function toObject(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return {};
+  }
+  return value;
+}
+
+function cleanDetails(details) {
+  const payload = toObject(details);
+  return Object.keys(payload).reduce((accumulator, key) => {
+    if (payload[key] !== undefined) {
+      accumulator[key] = payload[key];
+    }
+    return accumulator;
+  }, {});
+}
+
+function createResult(status, code, message, details = {}) {
+  return {
+    status,
+    code,
+    message: String(message || "").trim() || "(no message provided)",
+    details: cleanDetails(details)
+  };
+}
+
+function blocked(code, message, details = {}) {
+  return createResult(SAVE_STATUS.BLOCKED, code, message, details);
+}
+
+function unavailable(code, message, details = {}) {
+  return createResult(SAVE_STATUS.UNAVAILABLE, code, message, details);
+}
+
+function saved(message, details = {}) {
+  return createResult(SAVE_STATUS.SAVED, SAVE_CODES.SAVE_COMPLETED, message, details);
+}
+
+function mapValidationCodeToSaveCode(reasonCode) {
+  switch (reasonCode) {
+    case "registered_pen_missing":
+      return SAVE_CODES.REGISTERED_PEN_MISSING;
+    case "registered_pen_outside_project_root":
+    case "registered_pen_not_pen_path":
+      return SAVE_CODES.REGISTERED_PEN_INVALID;
+    case "session_pen_missing":
+      return SAVE_CODES.SESSION_PEN_MISSING;
+    case "session_pen_outside_project_root":
+    case "session_pen_not_pen_path":
+      return SAVE_CODES.SESSION_PEN_INVALID;
+    case "active_editor_missing":
+      return SAVE_CODES.ACTIVE_EDITOR_MISSING;
+    case "active_editor_new":
+      return SAVE_CODES.ACTIVE_EDITOR_NEW;
+    case "active_editor_outside_project_root":
+    case "active_editor_not_pen_path":
+      return SAVE_CODES.ACTIVE_EDITOR_INVALID;
+    default:
+      return SAVE_CODES.BOUND_SOURCE_MISMATCH;
+  }
+}
+
+function buildValidationMessage(reasonCode) {
+  switch (reasonCode) {
+    case "registered_pen_missing":
+      return "Registered project-local `.pen` path is missing.";
+    case "registered_pen_outside_project_root":
+      return "Registered `.pen` path resolves outside the project root.";
+    case "registered_pen_not_pen_path":
+      return "Registered `.pen` path does not end with `.pen`.";
+    case "session_pen_missing":
+      return "Session-bound `.pen` path is missing.";
+    case "session_pen_outside_project_root":
+      return "Session-bound `.pen` path resolves outside the project root.";
+    case "session_pen_not_pen_path":
+      return "Session-bound `.pen` path does not end with `.pen`.";
+    case "active_editor_missing":
+      return "Active editor path is missing from runtime state.";
+    case "active_editor_new":
+      return "Active editor is still `new`; save cannot continue.";
+    case "active_editor_outside_project_root":
+      return "Active editor path resolves outside the project root.";
+    case "active_editor_not_pen_path":
+      return "Active editor path does not end with `.pen`.";
+    default:
+      return "Registered, session, and active editor sources did not converge.";
+  }
+}
+
+function normalizeProjectRoot(projectPath) {
+  return path.resolve(projectPath || process.cwd());
+}
+
+function extractActiveEditorPath(editorState) {
+  if (typeof editorState === "string") {
+    return editorState.trim();
+  }
+
+  const payload = toObject(editorState);
+  if (typeof payload.activeEditorPath === "string") {
+    return payload.activeEditorPath.trim();
+  }
+  if (typeof payload.activeEditor === "string") {
+    return payload.activeEditor.trim();
+  }
+  if (typeof payload.filePath === "string") {
+    return payload.filePath.trim();
+  }
+  if (payload.editor && typeof payload.editor.filePath === "string") {
+    return payload.editor.filePath.trim();
+  }
+  return "";
+}
+
+function resolveBridgeMethod(bridge, methodNames) {
+  for (const name of methodNames) {
+    if (bridge && typeof bridge[name] === "function") {
+      return bridge[name].bind(bridge);
+    }
+  }
+  return null;
+}
+
+async function invokeBridgeMethod(bridge, methodNames, args, failureCode, failureMessage) {
+  const method = resolveBridgeMethod(bridge, methodNames);
+  if (!method) {
+    return unavailable(
+      SAVE_CODES.MCP_BRIDGE_UNAVAILABLE,
+      "Runtime cannot access the MCP bridge required for Save Current Design.",
+      {
+        missingMethod: methodNames[0]
+      }
+    );
+  }
+
+  try {
+    const value = await Promise.resolve(method(args));
+    return {
+      status: "ok",
+      value
+    };
+  } catch (error) {
+    return unavailable(failureCode, failureMessage, {
+      error: error && error.message ? error.message : String(error || "unknown bridge error")
+    });
+  }
+}
+
+function readBoundPenVersion(boundPenPath) {
+  const resolvedPath = path.resolve(boundPenPath);
+  if (!fs.existsSync(resolvedPath)) {
+    return blocked(
+      SAVE_CODES.BOUND_PEN_MISSING,
+      "Bound `.pen` file is missing on disk.",
+      {
+        boundPenPath: resolvedPath
+      }
+    );
+  }
+
+  try {
+    const payload = readPenDocument(resolvedPath);
+    const version =
+      payload && typeof payload.version === "string" && payload.version.trim()
+        ? payload.version.trim()
+        : "";
+    if (!version) {
+      return blocked(
+        SAVE_CODES.BOUND_PEN_VERSION_UNREADABLE,
+        "Bound `.pen` version is missing or empty; Save Current Design requires explicit versioning.",
+        {
+          boundPenPath: resolvedPath
+        }
+      );
+    }
+    return {
+      status: "PASS",
+      boundPenPath: resolvedPath,
+      version
+    };
+  } catch (error) {
+    return blocked(
+      SAVE_CODES.BOUND_PEN_VERSION_UNREADABLE,
+      "Unable to resolve bound `.pen` version from disk.",
+      {
+        boundPenPath: resolvedPath,
+        error: error && error.message ? error.message : String(error)
+      }
+    );
+  }
+}
+
+function buildBridgeCommand(method, args = {}) {
+  if (method === "get_variables") {
+    return "get_variables()";
+  }
+  return `${method}(${JSON.stringify(toObject(args))})`;
+}
+
+function createLocalPencilBridge(options = {}) {
+  const penPath = String(options.penPath || "").trim();
+  if (!penPath) {
+    return null;
+  }
+  const resolvedPenPath = path.resolve(penPath);
+  const pencilOptions = {
+    pencilBin: options.pencilBin,
+    pencilTimeoutMs: options.pencilTimeoutMs,
+    maxBuffer: options.maxBuffer
+  };
+
+  function runAndParse(method, args) {
+    const command = buildBridgeCommand(method, args);
+    const output = runPencilInteractive(resolvedPenPath, [command], pencilOptions);
+    return extractFirstJson(output);
+  }
+
+  return {
+    get_editor_state(args = {}) {
+      try {
+        return runAndParse("get_editor_state", args);
+      } catch (_error) {
+        return { activeEditor: resolvedPenPath };
+      }
+    },
+    batch_get(args = {}) {
+      return runAndParse("batch_get", args);
+    },
+    get_variables() {
+      return runAndParse("get_variables");
+    }
+  };
+}
+
+function validateBoundDesignSource(input = {}) {
+  const projectRoot = normalizeProjectRoot(input.projectRoot);
+  const registered = normalizeRegisteredPenPath(projectRoot, input.registeredPenPath);
+  if (!registered.ok) {
+    return {
+      status: "BLOCK",
+      blockerCode: mapValidationCodeToSaveCode(registered.code),
+      reasonCode: registered.code,
+      message: buildValidationMessage(registered.code),
+      details: {
+        projectRoot,
+        registeredPenPath: input.registeredPenPath || "",
+        sessionPenPath: input.sessionPenPath || "",
+        activeEditorPath: input.activeEditorPath || "",
+        registeredResolvedPath: registered.resolvedPath || ""
+      }
+    };
+  }
+
+  const session = normalizeSessionPenPath(projectRoot, input.sessionPenPath);
+  if (!session.ok) {
+    return {
+      status: "BLOCK",
+      blockerCode: mapValidationCodeToSaveCode(session.code),
+      reasonCode: session.code,
+      message: buildValidationMessage(session.code),
+      details: {
+        projectRoot,
+        registeredPenPath: input.registeredPenPath || "",
+        sessionPenPath: input.sessionPenPath || "",
+        activeEditorPath: input.activeEditorPath || "",
+        sessionResolvedPath: session.resolvedPath || ""
+      }
+    };
+  }
+
+  const editor = normalizeActiveEditorPath(projectRoot, input.activeEditorPath);
+  if (!editor.ok) {
+    return {
+      status: "BLOCK",
+      blockerCode: mapValidationCodeToSaveCode(editor.code),
+      reasonCode: editor.code,
+      message: buildValidationMessage(editor.code),
+      details: {
+        projectRoot,
+        registeredPenPath: input.registeredPenPath || "",
+        sessionPenPath: input.sessionPenPath || "",
+        activeEditorPath: input.activeEditorPath || "",
+        activeEditorResolvedPath: editor.resolvedPath || ""
+      }
+    };
+  }
+
+  const resolvedPaths = [registered.resolvedPath, session.resolvedPath, editor.resolvedPath];
+  const uniqueResolved = Array.from(new Set(resolvedPaths));
+  if (uniqueResolved.length !== 1) {
+    return {
+      status: "BLOCK",
+      blockerCode: SAVE_CODES.BOUND_SOURCE_MISMATCH,
+      reasonCode: "bound_source_mismatch",
+      message: "Registered, session, and active editor sources do not converge on one `.pen` file.",
+      details: {
+        projectRoot,
+        registeredResolvedPath: registered.resolvedPath,
+        sessionResolvedPath: session.resolvedPath,
+        activeEditorResolvedPath: editor.resolvedPath
+      }
+    };
+  }
+
+  return {
+    status: "PASS",
+    boundPenPath: uniqueResolved[0]
+  };
+}
+
+function normalizeSnapshotPayloads(nodesPayload, variablesPayload) {
+  let normalizedNodes;
+  try {
+    normalizedNodes = normalizeNodesPayload(nodesPayload);
+  } catch (error) {
+    const message = error && error.message ? error.message : String(error);
+    const truncated = /truncated/i.test(message);
+    return blocked(
+      truncated ? SAVE_CODES.SNAPSHOT_NODES_TRUNCATED : SAVE_CODES.SNAPSHOT_NODES_INVALID,
+      truncated
+        ? "Live nodes payload is truncated (`...`); save is blocked until a complete snapshot is captured."
+        : "Live nodes payload is invalid for persistence.",
+      { error: message }
+    );
+  }
+
+  let normalizedVariables;
+  try {
+    normalizedVariables = normalizeVariablesPayload(variablesPayload) || {};
+  } catch (error) {
+    return blocked(
+      SAVE_CODES.SNAPSHOT_VARIABLES_INVALID,
+      "Live variables payload is invalid for persistence.",
+      {
+        error: error && error.message ? error.message : String(error)
+      }
+    );
+  }
+
+  return {
+    status: "PASS",
+    nodes: normalizedNodes,
+    variables: normalizedVariables
+  };
+}
+
+async function captureLivePencilSnapshot(options = {}) {
+  const projectRoot = normalizeProjectRoot(options.projectRoot);
+  const bridge = options.bridge;
+  const readDepth =
+    Number.isFinite(Number(options.readDepth)) && Number(options.readDepth) > 0
+      ? Number(options.readDepth)
+      : DEFAULT_READ_DEPTH;
+
+  if (!bridge || typeof bridge !== "object") {
+    return unavailable(
+      SAVE_CODES.MCP_BRIDGE_UNAVAILABLE,
+      "Runtime cannot access the MCP bridge required for live snapshot capture."
+    );
+  }
+
+  const firstEditorRead = await invokeBridgeMethod(
+    bridge,
+    ["get_editor_state", "getEditorState"],
+    { include_schema: false },
+    SAVE_CODES.MCP_EDITOR_STATE_UNAVAILABLE,
+    "Runtime could not read the active editor before snapshot capture."
+  );
+  if (firstEditorRead.status !== "ok") {
+    return firstEditorRead;
+  }
+  const firstActiveEditorPath = extractActiveEditorPath(firstEditorRead.value);
+
+  const firstValidation = validateBoundDesignSource({
+    projectRoot,
+    registeredPenPath: options.registeredPenPath,
+    sessionPenPath: options.sessionPenPath,
+    activeEditorPath: firstActiveEditorPath
+  });
+  if (firstValidation.status === "BLOCK") {
+    return blocked(firstValidation.blockerCode, firstValidation.message, {
+      ...firstValidation.details,
+      phase: "before_capture"
+    });
+  }
+
+  const nodesRead = await invokeBridgeMethod(
+    bridge,
+    ["batch_get", "batchGet"],
+    {
+      readDepth,
+      includePathGeometry: true,
+      resolveInstances: false,
+      resolveVariables: false
+    },
+    SAVE_CODES.MCP_SNAPSHOT_UNAVAILABLE,
+    "Runtime could not capture live nodes from the MCP bridge."
+  );
+  if (nodesRead.status !== "ok") {
+    return nodesRead;
+  }
+
+  const variablesRead = await invokeBridgeMethod(
+    bridge,
+    ["get_variables", "getVariables"],
+    {},
+    SAVE_CODES.MCP_SNAPSHOT_UNAVAILABLE,
+    "Runtime could not capture live variables from the MCP bridge."
+  );
+  if (variablesRead.status !== "ok") {
+    return variablesRead;
+  }
+
+  const snapshotPayload = normalizeSnapshotPayloads(nodesRead.value, variablesRead.value);
+  if (snapshotPayload.status === SAVE_STATUS.BLOCKED) {
+    return snapshotPayload;
+  }
+
+  const secondEditorRead = await invokeBridgeMethod(
+    bridge,
+    ["get_editor_state", "getEditorState"],
+    { include_schema: false },
+    SAVE_CODES.MCP_EDITOR_STATE_UNAVAILABLE,
+    "Runtime could not read the active editor after snapshot capture."
+  );
+  if (secondEditorRead.status !== "ok") {
+    return secondEditorRead;
+  }
+  const secondActiveEditorPath = extractActiveEditorPath(secondEditorRead.value);
+
+  const secondValidation = validateBoundDesignSource({
+    projectRoot,
+    registeredPenPath: options.registeredPenPath,
+    sessionPenPath: options.sessionPenPath,
+    activeEditorPath: secondActiveEditorPath
+  });
+  if (secondValidation.status === "BLOCK") {
+    return blocked(
+      SAVE_CODES.ACTIVE_EDITOR_DRIFT,
+      "Active editor drifted during snapshot capture; save is blocked.",
+      {
+        phase: "after_capture",
+        firstActiveEditorPath,
+        secondActiveEditorPath,
+        firstBoundPenPath: firstValidation.boundPenPath || "",
+        secondBoundPenPath: "",
+        driftReasonCode: secondValidation.reasonCode
+      }
+    );
+  }
+
+  if (secondValidation.boundPenPath !== firstValidation.boundPenPath) {
+    return blocked(
+      SAVE_CODES.ACTIVE_EDITOR_DRIFT,
+      "Active editor drifted during snapshot capture; save is blocked.",
+      {
+        phase: "after_capture",
+        firstActiveEditorPath,
+        secondActiveEditorPath,
+        firstBoundPenPath: firstValidation.boundPenPath || "",
+        secondBoundPenPath: secondValidation.boundPenPath || "",
+        driftReasonCode: "bound_source_mismatch"
+      }
+    );
+  }
+
+  return {
+    status: "PASS",
+    boundPenPath: firstValidation.boundPenPath,
+    firstActiveEditorPath,
+    secondActiveEditorPath,
+    nodes: snapshotPayload.nodes,
+    variables: snapshotPayload.variables
+  };
+}
+
+function materializeSnapshotFiles(snapshot) {
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "da-vinci-save-current-design-"));
+  const nodesFile = path.join(tempDir, "nodes.json");
+  const variablesFile = path.join(tempDir, "variables.json");
+
+  fs.writeFileSync(nodesFile, JSON.stringify({ nodes: snapshot.nodes }, null, 2));
+  fs.writeFileSync(variablesFile, JSON.stringify({ variables: snapshot.variables || {} }, null, 2));
+
+  return {
+    tempDir,
+    nodesFile,
+    variablesFile
+  };
+}
+
+function preflightSessionAndLock(projectRoot, registeredPenPath, options = {}) {
+  let session;
+  try {
+    session = readSessionState(projectRoot);
+  } catch (error) {
+    return blocked(
+      SAVE_CODES.SESSION_STATE_INVALID,
+      "Pencil session state is unreadable. Repair or restart the session before saving.",
+      {
+        projectRoot,
+        error: error && error.message ? error.message : String(error)
+      }
+    );
+  }
+  if (!session) {
+    return blocked(
+      SAVE_CODES.SESSION_STATE_MISSING,
+      "Pencil session state is missing. Start or resume a session before saving.",
+      {
+        projectRoot
+      }
+    );
+  }
+
+  if (session.status !== "active") {
+    return blocked(
+      SAVE_CODES.SESSION_NOT_ACTIVE,
+      "Pencil session is not active. Resume an active session before saving.",
+      {
+        projectRoot,
+        sessionStatus: session.status
+      }
+    );
+  }
+
+  const lockStatus = getPencilLockStatus({ homeDir: options.homeDir });
+  if (!lockStatus.lock) {
+    return blocked(
+      SAVE_CODES.LOCK_MISSING,
+      "Pencil lock is missing. Save Current Design cannot proceed without lock ownership.",
+      {
+        lockPath: lockStatus.lockPath
+      }
+    );
+  }
+
+  const lock = lockStatus.lock;
+  if (typeof lock !== "object" || lock.__invalid) {
+    return blocked(
+      SAVE_CODES.LOCK_INVALID,
+      "Pencil lock payload is invalid; Save Current Design cannot trust lock ownership.",
+      {
+        lockPath: lockStatus.lockPath
+      }
+    );
+  }
+
+  if (typeof lock.projectPath !== "string" || !lock.projectPath.trim()) {
+    return blocked(
+      SAVE_CODES.LOCK_INVALID,
+      "Pencil lock payload is missing `projectPath`; Save Current Design cannot verify lock ownership.",
+      {
+        lockPath: lockStatus.lockPath
+      }
+    );
+  }
+
+  if (isStaleLock(lock)) {
+    return blocked(
+      SAVE_CODES.LOCK_STALE,
+      "Pencil lock appears stale; restart the session before saving.",
+      {
+        lockPath: lockStatus.lockPath,
+        lockProjectPath: typeof lock.projectPath === "string" ? lock.projectPath : ""
+      }
+    );
+  }
+
+  const lockProjectPath = path.resolve(lock.projectPath);
+  if (lockProjectPath !== path.resolve(projectRoot)) {
+    return blocked(
+      SAVE_CODES.LOCK_OWNED_BY_OTHER_PROJECT,
+      "Pencil lock is currently owned by a different project.",
+      {
+        lockPath: lockStatus.lockPath,
+        lockProjectPath
+      }
+    );
+  }
+
+  const versionCheck = readBoundPenVersion(registeredPenPath);
+  if (versionCheck.status === SAVE_STATUS.BLOCKED) {
+    return versionCheck;
+  }
+
+  return {
+    status: "PASS",
+    session,
+    lockStatus,
+    penVersion: versionCheck.version,
+    registeredPenPath: versionCheck.boundPenPath
+  };
+}
+
+async function saveCurrentDesign(options = {}) {
+  const projectRoot = normalizeProjectRoot(options.projectPath);
+  const registryPath = path.join(projectRoot, ".da-vinci", "design-registry.md");
+  const registryText = readTextIfExists(registryPath);
+  const registeredPenPath = resolvePreferredRegisteredPenPath(projectRoot, registryText);
+
+  if (!registeredPenPath) {
+    return blocked(
+      SAVE_CODES.REGISTERED_PEN_MISSING,
+      "No registered project-local `.pen` source was found in `.da-vinci/design-registry.md`.",
+      {
+        projectRoot,
+        registryPath
+      }
+    );
+  }
+
+  const preflight = preflightSessionAndLock(projectRoot, registeredPenPath, {
+    homeDir: options.homeDir
+  });
+  if (preflight.status === SAVE_STATUS.BLOCKED) {
+    return preflight;
+  }
+
+  const capture = await captureLivePencilSnapshot({
+    projectRoot,
+    registeredPenPath,
+    sessionPenPath: preflight.session.penPath,
+    bridge:
+      options.bridge ||
+      (options.allowLocalBridge === true
+        ? createLocalPencilBridge({
+            penPath: preflight.session.penPath,
+            pencilBin: options.pencilBin,
+            pencilTimeoutMs: options.pencilTimeoutMs,
+            maxBuffer: options.maxBuffer
+          })
+        : null),
+    readDepth: options.readDepth
+  });
+
+  if (capture.status === SAVE_STATUS.BLOCKED || capture.status === SAVE_STATUS.UNAVAILABLE) {
+    return capture;
+  }
+
+  const persistSession =
+    typeof options.persistSession === "function" ? options.persistSession : persistPencilSession;
+
+  let materialized = null;
+  try {
+    materialized = materializeSnapshotFiles(capture);
+    let persistResult;
+    try {
+      persistResult = persistSession({
+        projectPath: projectRoot,
+        penPath: capture.boundPenPath,
+        nodesFile: materialized.nodesFile,
+        variablesFile: materialized.variablesFile,
+        version: preflight.penVersion,
+        homeDir: options.homeDir
+      });
+    } catch (error) {
+      return blocked(
+        SAVE_CODES.PERSIST_FAILED,
+        "High-level save failed while persisting the validated live snapshot.",
+        {
+          projectRoot,
+          boundPenPath: capture.boundPenPath,
+          error: error && error.message ? error.message : String(error)
+        }
+      );
+    }
+
+    const syncResult = persistResult.syncResult || null;
+    if (!syncResult || syncResult.inSync !== true) {
+      return blocked(
+        SAVE_CODES.PERSIST_NOT_IN_SYNC,
+        "Persistence completed, but the sync signal reports `inSync === false`.",
+        {
+          projectRoot,
+          boundPenPath: capture.boundPenPath,
+          inSync: Boolean(syncResult && syncResult.inSync),
+          persistedHash: syncResult ? syncResult.persistedHash : null,
+          liveHash: syncResult ? syncResult.liveHash : null
+        }
+      );
+    }
+
+    return saved("Current design was saved through the bound-source persistence flow.", {
+      projectRoot,
+      boundPenPath: capture.boundPenPath,
+      penVersion: preflight.penVersion,
+      syncResult: {
+        inSync: syncResult.inSync,
+        persistedHash: syncResult.persistedHash,
+        liveHash: syncResult.liveHash
+      }
+    });
+  } finally {
+    if (materialized && materialized.tempDir) {
+      fs.rmSync(materialized.tempDir, { recursive: true, force: true });
+    }
+  }
+}
+
+function formatSaveCurrentDesignReport(result) {
+  const payload = toObject(result);
+  const status = String(payload.status || "unknown").toUpperCase();
+  const details = toObject(payload.details);
+  const lines = [
+    "Da Vinci Save Current Design",
+    `Status: ${status}`,
+    `Code: ${payload.code || "(missing)"}`,
+    `Message: ${payload.message || "(missing)"}`
+  ];
+
+  if (details.boundPenPath) {
+    lines.push(`Bound .pen: ${details.boundPenPath}`);
+  }
+  if (details.projectRoot) {
+    lines.push(`Project: ${details.projectRoot}`);
+  }
+  if (payload.status === SAVE_STATUS.UNAVAILABLE) {
+    lines.push("Bridge: unavailable");
+  }
+
+  return lines.join("\n");
+}
+
+module.exports = {
+  SAVE_STATUS,
+  SAVE_CODES,
+  createLocalPencilBridge,
+  validateBoundDesignSource,
+  captureLivePencilSnapshot,
+  saveCurrentDesign,
+  formatSaveCurrentDesignReport
+};