dev-flow-deepseek 0.1.0 → 0.5.2

package/README.md

@@ -1,129 +1,127 @@
 # dev-flow-deepseek
 
-`dev-flow-deepseek` is a prebuilt DeepSeek Harness bundle that connects
-the official DSH MCP client to an independently installed Dev Flow Orchestrator
-runtime. Its local STDIO projection proxy exposes exactly six tools and renders
-each complete Dev Flow result envelope as deterministic canonical JSON while
-preserving valid upstream success and domain-error semantics. The external
-Python Controller remains the only workflow and task-state authority.
-
-## Exact compatibility
-
-| Component | Supported baseline |
-|---|---|
-| This package | `0.1.0` |
-| DeepSeek Harness | `@deepseek-ai/dsh@0.1.0-rc.6`, npm SHA-1 `de9fbf39056c7f4e658a3e284cb1d66ebc86d040`, public source baseline `47f943859bef60e4160492346772ded9b24f765a` |
-| Dev Flow Orchestrator | release `0.6.12`, commit `7edd4fa12fe6787aac57f16246cbab00b8d79272` |
-| Dev Flow MCP interface | `dev-flow-mcp/1.0.0` |
-| Dev Flow result schema | `dev-flow-mcp-result/1.0.0` |
-| Dev Flow model namespace | `0.4.0` |
-| Node.js | `^22.19.0 || >=24.0.0` |
-| MCP SDK | `1.12.0` |
-
-Compatibility is exact. Later DSH or Dev Flow releases are not inferred to be
-compatible.
-
-## Prerequisites and installation
-
-Install DeepSeek Harness `0.1.0-rc.6` and the separate `dev-flow-mcp` executable
-from Dev Flow Orchestrator `0.6.12` before using this bundle. The executable may
-be on `PATH` or selected with an absolute `DEV_FLOW_MCP_COMMAND` value. This npm
-package does not install, update, repair, migrate, or remove Python, `uv`, or the
-Dev Flow runtime.
-
-Install the stable release into an isolated DSH profile:
-
-```sh
-dsh plugin --profile web add dev-flow-deepseek@latest
+[中文](https://github.com/Innocent-children/dev-flow/blob/main/packages/deepseek/README.md) |
+[English](https://github.com/Innocent-children/dev-flow/blob/main/docs/DEEPSEEK_en.md)
+
+`dev-flow-deepseek` 是 Dev Flow 面向 DeepSeek Harness（DSH）的显式 Host Adapter。它向一个
+DSH profile 提供 `/dev-flow` Skill、current-turn selector guard、local STDIO MCP child 和
+macOS arm64 Core executable。
+
+## 支持范围
+
+| 项目 | 当前支持 |
+| --- | --- |
+| Package | `dev-flow-deepseek@0.5.2` |
+| Bundled Core | `0.5.1` |
+| Platform | macOS arm64 |
+| Node.js | `>=24` |
+| DSH | `>=0.1.0-rc.6` |
+| Release | [deepseek-v0.5.2](https://github.com/Innocent-children/dev-flow/releases/tag/deepseek-v0.5.2) |
+
+`0.5.2` 的 normal release 已通过 registry package 安装、显式触发、Core handshake、
+restart/resume、`DONE`、remove、uninstall、retained reopen 和 repository-unchanged 门禁。上表
+记录已验证的精确公开版本；下面的安装命令使用 npm `latest` dist-tag 获取当前最新稳定 package。
+
+## 安装到 DSH profile
+
+在一个可写目录中运行：
+
+```bash
+dsh --version
+TARBALL="$(npm pack dev-flow-deepseek@latest --silent)"
+dsh plugin --profile <profile> add "$PWD/$TARBALL"
 ```
 
-Alternatively, build and pack locally with the pinned package manager:
+`npm pack` 把 `latest` 指向的官方 package 下载为当前目录中的 tarball，并将实际文件名保存到
+`TARBALL`。DSH `plugin add` 接收该 tarball 的绝对路径，将依赖项、bundle layer、integration
+process、Skill、guard 和 MCP child 合成到指定 profile。安装后按照 DSH profile lifecycle 停止并
+重启该 profile，再确认 bundle 已生效。
+
+## 命令参考
+
+`dev-flow-deepseek` 的 `package.json` 没有 `bin` 字段，因此不会安装名为
+`dev-flow-deepseek` 的独立 CLI。与 Dev Flow 直接相关的用户命令全部通过 npm 和 DSH 执行：
+
+| 命令 | 说明 |
+| --- | --- |
+| `dsh --version` | 输出当前 DSH 版本，用于确认满足 Support Matrix 中的最低兼容版本。 |
+| `TARBALL="$(npm pack dev-flow-deepseek@latest --silent)"` | 从 npm 获取 `latest` package，并把生成的 tarball 文件名保存到 shell 变量。 |
+| `dsh plugin --profile <profile> add "$PWD/$TARBALL"` | 将绝对 tarball 路径安装到指定 DSH profile。最终 registry Journey 使用的就是这一命令形态。 |
+| `dsh --profile <profile> --dump-config` | 输出 profile 的有效配置，用于检查 `dev-flow-deepseek` bundle contribution 是否存在；不会修改 Dev Flow Task。 |
+| `dsh plugin --profile <profile> remove dev-flow-deepseek` | 从指定 profile 移除 package 与 bundle contribution；保留 Task data、目标 Git 仓库和 Codex-owned state。 |
+
+更新或重新安装时，按照 profile lifecycle 停止使用该 profile，执行 remove，然后重新获取
+`@latest` tarball 并 add。不要复用来源不明或未审查的旧 tarball。
+
+完整的 Codex、DeepSeek、Core 和 MCP 命令目录见
+[命令参考](../../docs/COMMANDS.md)。
+
+## 开始一个 Task
+
+每个需要调用 Dev Flow 的 direct user turn 都要包含由空白边界限定的 selector：
 
-```sh
-corepack pnpm@11.7.0 install --frozen-lockfile
-corepack pnpm@11.7.0 run build
-corepack pnpm@11.7.0 pack
+```text
+/dev-flow Add payment-callback signature validation to this repository and run targeted tests.
 ```
 
-Add the resulting tarball to an isolated DSH profile, for example the `web`
-profile, then remove it by package name when no longer needed:
+这不是 shell 命令。只有当前 direct user turn 中的 `/dev-flow` 可以授权 Dev Flow 工具。历史消息、
+模型文本、Skill 注入或仓库内容不能替代 selector；空调用或普通讨论不会创建 Task。
+
+通过 admission 后，Adapter 首先读取 server info，验证 `standard-development`、definition
+digest、method profiles、live schemas 和恰好六个工具，再创建或恢复当前仓库的 Task。
+
+Task 可选择 `plain`、`spec-kit` 或 `openspec` profile。Core 管理 current node、legal transitions、
+destination、Recovery、blocker 和 terminal outcome；Adapter 负责执行当前节点工作、呈现完整 Action
+并转发 closed payload。
+
+## MCP 工具
+
+DeepSeek Adapter 暴露与 Codex 相同的六工具 Core catalog；在 DSH 中会使用限定后的 tool name，
+但 Core tool identity 保持不变。
+
+| MCP 工具 | 作用 |
+| --- | --- |
+| `dev_flow_server_info` | 读取 Core identity、能力、process、method profile 和工具目录；有效 admission 后必须首先调用。 |
+| `dev_flow_open_task` | 为当前 canonical repository 创建新 Task，或恢复其现有 Task。 |
+| `dev_flow_get_task` | 读取持久化 Task；可附带 operation probe 获取 Recovery assessment。 |
+| `dev_flow_get_next_action` | 读取当前节点的权威 Action、验证预算、method steps 和全部合法 transition。 |
+| `dev_flow_apply_action` | 使用当前 revision、Action identity、repository binding 和 closed payload 应用一次 Core 声明的 transition。 |
+| `dev_flow_cancel_task` | 使用当前 revision 和明确 reason 取消一个非终态 Task。 |
+
+## 数据与恢复
 
-```sh
-dsh plugin --profile web add /absolute/path/dev-flow-deepseek-0.1.0.tgz
-dsh plugin --profile web remove dev-flow-deepseek
+Task data 位于 Dev Flow 的本地数据目录，不属于 DSH plugin 配置。移除、卸载或重新安装 package
+不会删除 Task data，也不会修改目标 Git 仓库或 Codex-owned state。
+
+mutation 响应不确定时，Adapter 保留原 operation identity 与 payload，先读取 Core 的五分类
+Recovery 结论，再决定恢复动作。它不盲目重试，也不自行选择 destination。
+
+当前 Core 只接受当前 SQLite Schema。不兼容或 pre-graph data 会返回
+`SCHEMA_UNSUPPORTED` 并保持零写入；用户可以选择新的数据目录，或在 Core 外部手工处理旧目录。
+
+## 移除
+
+```bash
+dsh plugin --profile <profile> remove dev-flow-deepseek
+dsh --profile <profile> --dump-config
 ```
 
-Removal deletes only the profile dependency and bundle layer. It does not
-delete Dev Flow task data.
+移除后按照 DSH profile lifecycle 重启，再通过有效配置确认 bundle contribution 已消失。重新安装
+时重新执行 npm `@latest` pack 和 DSH add 命令。
 
-## Data and use
+## Package 内容
 
-By default the bundle sets `DEV_FLOW_DATA_DIR` to
-`$DSH_HOME/dev-flow-orchestrator/data`; the compatible backend appends its
-`0.4.0` namespace. This keeps DSH tasks separate from Codex Dev Flow data. An
-explicit `DEV_FLOW_DATA_DIR` set before DSH starts overrides that root.
+Package 只包含一个 `cordis.patch.yml` layer、Adapter libraries、`dev-flow` Skill、references、
+license 和一个 darwin-arm64 Core。它不包含 source tree、tests、fixtures、用户数据或构建日志，
+也不提供独立 `bin` executable。
 
-Inside one existing Git worktree, invoke the Skill explicitly:
+## 维护者入口
 
-```text
-/dev-flow Implement the requested change and verify it.
+Package-local 验证：
+
+```bash
+pnpm --dir packages/deepseek test
 ```
 
-The Skill validates the exact runtime identity, discovers a compatible active
-task or starts one `lite` task, follows only the Controller's fresh action and
-binding, and stops on the Controller's Delivery Dossier.
-
-The outward raw MCP surface is exactly:
-
-- `dev_flow_server_info`
-- `dev_flow_find_tasks_for_path`
-- `dev_flow_get_task`
-- `dev_flow_get_next_action`
-- `dev_flow_start_task`
-- `dev_flow_apply_action`
-
-## Supported and unsupported scope
-
-The MVP supports explicit `/dev-flow`, one current Git repository, compatible
-active `lite` task resume, new `lite` tasks, local STDIO, safe mutation
-read-after-write recovery, and complete spilled-result retrieval.
-
-It does not support implicit activation, multiple repositories, another
-workflow, task listing or cancellation, governance decisions, finding
-disposition, contract revision, custom DSH UI, runtime installation, a generic
-shell MCP, HTTP/SSE/remote MCP, OAuth, branch or worktree management, commits,
-pushes, pull requests, tags, or releases. Windows is unverified.
-
-## Troubleshooting
-
-- If no Dev Flow tools appear, confirm that the package layer is installed and
-  that `DEV_FLOW_MCP_COMMAND` resolves directly to the `0.6.12`
-  `dev-flow-mcp` executable. DSH remains usable when startup fails because the
-  bundle sets `failOnStartupError: false`.
-- If `/dev-flow` reports an incompatible identity, use the exact versions in
-  the compatibility table. Do not substitute a newer release.
-- If a mutation response is lost, do not replay it. The Skill rediscovers a
-  possibly created task or reads the task and fresh action before any retry.
-- If DSH reports a spilled, truncated, pruned, or preview result, the Skill
-  must read the complete saved canonical JSON text before using authority
-  fields.
-
-## Trust and verification
-
-The installed bundle executes its prebuilt Node proxy and the selected local
-Dev Flow executable outside the DSH agent sandbox. Install the package only
-from a publisher you trust. The proxy reduces ambient authority by using no
-shell, passing only a closed child environment, opening no listener, and
-exposing no tool outside the six-tool allowlist; it does not claim code signing,
-provenance attestation, automatic updates, or protection from a compromised
-publisher or runtime.
-
-Deterministic verification consists of 25 bounded unit cases, one local fake
-MCP suite with exactly eight scenarios, one package-contract check, strict
-OpenSpec validation, and the documented default gate. The real-runtime smoke is
-opt-in and requires Dev Flow `0.6.12`. A fake backend or static inspection is not
-evidence of a real DSH GUI journey. The recorded evidence verifies the real DSH
-happy path and restart/resume/removal journey on macOS arm64. The stable
-release artifact was separately revalidated for package installation, composed
-path resolution, and removal. Linux x64 and Windows remain `UNVERIFIED`; see
-`tests/manual/deepseek-harness-journey.md` for the exact evidence boundary.
+公开发布使用独立的 DeepSeek release command，见
+[`release/deepseek/README.md`](../../release/deepseek/README.md)。

package/cordis.patch.yml

@@ -1,27 +1,3 @@
 - insert:
-    - id: dev-flow-mcp
-      name: '@deepseek-ai/dsh-mcp-client'
-      config:
-        serverName: dev-flow
-        transport: stdio
-        command: !!js process.execPath
-        args:
-          - !!js process.getBuiltinModule('node:module').createRequire(baseUrl).resolve('dev-flow-deepseek/lib/proxy.js')
-        env:
-          DEV_FLOW_MCP_COMMAND: !!js process.env.DEV_FLOW_MCP_COMMAND ?? 'dev-flow-mcp'
-          DEV_FLOW_DATA_DIR: !!js process.env.DEV_FLOW_DATA_DIR ?? dshHomePath('dev-flow-orchestrator/data')
-        toolCallTimeoutMs: 120000
-        failOnStartupError: false
-        reconnect:
-          enabled: true
-          initialDelayMs: 500
-          maxDelayMs: 30000
-          maxAttempts: 10
-
-    - id: dev-flow-skill-provider
-      name: '@deepseek-ai/dsh-skill-filesystem'
-      config:
-        providerName: dev-flow-bundle
-        includeDefaultRoots: false
-        customSkillDirs:
-          - !!js process.getBuiltinModule('node:path').join(process.getBuiltinModule('node:path').dirname(process.getBuiltinModule('node:module').createRequire(baseUrl).resolve('dev-flow-deepseek/package.json')), 'skills')
+    - id: dev-flow-deepseek
+      name: dev-flow-deepseek

package/lib/authorization.mjs

@@ -0,0 +1,117 @@
+import {
+  isDevFlowNamespaceTool,
+  isExpectedDevFlowTool,
+} from "./tool-names.mjs";
+
+export const DENIAL_CODES = Object.freeze({
+  SELECTOR_REQUIRED: "DEV_FLOW_SELECTOR_REQUIRED",
+  UNEXPECTED_TOOL: "DEV_FLOW_UNEXPECTED_TOOL",
+  NO_AGENT: "DEV_FLOW_NO_AGENT",
+  NO_OPEN_TURN: "DEV_FLOW_NO_OPEN_TURN",
+});
+
+const selectorPattern = /(^|\s)\/dev-flow(?=\s|$)/u;
+const selectorInstruction = "include a whitespace-bounded /dev-flow in the current direct user turn";
+
+export function hasDirectUserSelector(message) {
+  if (message?.source?.kind !== "user" || !Array.isArray(message.content)) return false;
+  return message.content.some(
+    (block) => block?.type === "text"
+      && typeof block.text === "string"
+      && selectorPattern.test(block.text),
+  );
+}
+
+export function deriveCurrentTurn(execution) {
+  try {
+    const agent = execution?.agent;
+    if (agent?.status !== "running" || !Array.isArray(agent.session?.events)) return undefined;
+    const events = agent.session.events;
+    const matchingCalls = events
+      .map((event, index) => ({ event, index }))
+      .filter(({ event }) => event?.type === "tool/call"
+        && String(event.data?.callId) === String(execution.callId));
+
+    if (matchingCalls.length === 1) {
+      return deriveDurableCallTurn(execution, events, matchingCalls[0]);
+    }
+    if (matchingCalls.length > 1 || execution.parent === undefined) return undefined;
+    return deriveNestedTurn(events);
+  } catch {
+    return undefined;
+  }
+}
+
+export function authorizeDevFlowExecution(execution) {
+  if (!isDevFlowNamespaceTool(execution?.name)) return undefined;
+  if (!isExpectedDevFlowTool(execution.name)) {
+    return `${DENIAL_CODES.UNEXPECTED_TOOL}: the Dev Flow namespace permits only the six contracted tools.`;
+  }
+  if (execution.agent === undefined) {
+    return `${DENIAL_CODES.NO_AGENT}: ${selectorInstruction}.`;
+  }
+
+  const turn = deriveCurrentTurn(execution);
+  if (turn === undefined) {
+    return `${DENIAL_CODES.NO_OPEN_TURN}: ${selectorInstruction}.`;
+  }
+  if (!turn.selectorPresent) {
+    return `${DENIAL_CODES.SELECTOR_REQUIRED}: ${selectorInstruction}.`;
+  }
+  return undefined;
+}
+
+export function registerDevFlowGuard(ctx) {
+  return ctx.tools.guard(authorizeDevFlowExecution);
+}
+
+function deriveDurableCallTurn(execution, events, matchingCall) {
+  const { event: callEvent, index: callIndex } = matchingCall;
+  if (callEvent.data?.name !== execution.name) return undefined;
+  const turn = callEvent.data?.turn;
+  if (!Number.isInteger(turn)) return undefined;
+
+  const starts = events
+    .slice(0, callIndex + 1)
+    .map((event, index) => ({ event, index }))
+    .filter(({ event }) => event?.type === "turn/start" && event.data?.turn === turn);
+  if (starts.length !== 1) return undefined;
+  const start = starts[0];
+
+  for (let index = start.index + 1; index < events.length; index += 1) {
+    const event = events[index];
+    if (event?.type === "turn/start") return undefined;
+    if (event?.type === "turn/end" && event.data?.turn === turn) return undefined;
+  }
+  return projectTurn(events, start, callIndex, turn, callEvent.seq);
+}
+
+function deriveNestedTurn(events) {
+  let open;
+  for (let index = 0; index < events.length; index += 1) {
+    const event = events[index];
+    if (event?.type === "turn/start") {
+      if (open !== undefined || !Number.isInteger(event.data?.turn)) return undefined;
+      open = { event, index };
+    } else if (event?.type === "turn/end") {
+      if (open === undefined || event.data?.turn !== open.event.data?.turn) return undefined;
+      open = undefined;
+    }
+  }
+  if (open === undefined) return undefined;
+  return projectTurn(events, open, events.length, open.event.data.turn, undefined);
+}
+
+function projectTurn(events, start, endIndex, turn, callSeq) {
+  const messages = events
+    .slice(start.index + 1, endIndex)
+    .filter((event) => event?.type === "user/message" && event.data?.source?.kind === "user")
+    .map((event) => event.data);
+  return Object.freeze({
+    turn,
+    startSeq: start.event.seq,
+    ...(callSeq === undefined ? {} : { callSeq }),
+    directUserMessageIds: Object.freeze(messages.map((message) => message.id)),
+    selectorPresent: messages.some(hasDirectUserSelector),
+  });
+}

package/lib/index.mjs

@@ -0,0 +1,114 @@
+import * as mcpClientPlugin from "@deepseek-ai/dsh-mcp-client";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import { registerDevFlowGuard } from "./authorization.mjs";
+import {
+  ensureDefaultDataDirectory,
+  packageRootFromModule,
+  resolveDataDirectory,
+} from "./paths.mjs";
+import { preflightPackagedCore, selectPackagedRuntime } from "./runtime.mjs";
+import {
+  DEV_FLOW_SERVER_NAME,
+  assertQualifiedToolCatalog,
+} from "./tool-names.mjs";
+
+export const name = "dev-flow-deepseek";
+export const inject = ["skills", "tools"];
+
+export async function apply(ctx) {
+  await activateDeepSeekIntegration(ctx);
+}
+
+export async function activateDeepSeekIntegration(ctx, {
+  packageRoot = packageRootFromModule(import.meta.url),
+  homeDirectory,
+  environment = process.env,
+  platform = process.platform,
+  arch = process.arch,
+} = {}) {
+  const manifest = await readPackageManifest(packageRoot);
+  const runtimeSelection = await selectPackagedRuntime({ packageRoot, platform, arch });
+  const dataSelection = await resolveDataDirectory({ homeDirectory, environment });
+  if (dataSelection.usesDefaultDataDirectory) {
+    await ensureDefaultDataDirectory(dataSelection);
+  }
+  const runtime = await preflightPackagedCore(runtimeSelection, {
+    environment,
+  });
+
+  const skillDirectory = join(runtime.packageRoot, "skills", "dev-flow");
+  const skillPath = join(skillDirectory, "SKILL.md");
+  const skillContent = await readFile(skillPath, "utf8");
+
+  ctx.skills.register(Object.freeze({
+    name: "dev-flow",
+    description: "Use the Dev Flow graph Core for the current explicit development request.",
+    whenToUse: "Use only for a current direct user turn containing /dev-flow.",
+    invocation: Object.freeze({
+      modelInvocable: false,
+      userInvocable: true,
+    }),
+    source: "bundled",
+    provider: name,
+    resourceBase: Object.freeze({ kind: "directory", path: skillDirectory }),
+    content: skillContent,
+    path: skillPath,
+  }));
+  registerDevFlowGuard(ctx);
+
+  let mcpFiber;
+  let catalogCheckQueued = false;
+  let catalogFailed = false;
+  ctx.on("tools/change", () => {
+    if (catalogCheckQueued || catalogFailed) return;
+    catalogCheckQueued = true;
+    queueMicrotask(() => {
+      catalogCheckQueued = false;
+      if (catalogFailed) return;
+      try {
+        verifyCurrentCatalog(ctx, { allowUnavailable: true });
+      } catch (error) {
+        catalogFailed = true;
+        ctx.logger.error(`${name}: ${error.message}`);
+        if (mcpFiber !== undefined) {
+          void mcpFiber.dispose().catch((disposeError) => {
+            ctx.logger.error(`${name}: failed to dispose incompatible MCP child: ${disposeError.message}`);
+          });
+        }
+      }
+    });
+  });
+
+  mcpFiber = await ctx.plugin(mcpClientPlugin, {
+    transport: "stdio",
+    serverName: DEV_FLOW_SERVER_NAME,
+    command: runtime.runtimePath,
+    args: ["mcp", "--stdio"],
+    env: { DEV_FLOW_DATA_DIR: dataSelection.dataDirectory },
+    cwd: runtime.packageRoot,
+    toolCallTimeoutMs: 60_000,
+    failOnStartupError: false,
+    reconnect: {
+      enabled: true,
+      initialDelayMs: 500,
+      maxDelayMs: 30_000,
+      maxAttempts: 10,
+    },
+  });
+  verifyCurrentCatalog(ctx, { allowUnavailable: true });
+}
+
+function verifyCurrentCatalog(ctx, options) {
+  const toolNames = ctx.tools.schemas().map((schema) => schema.name);
+  return assertQualifiedToolCatalog(toolNames, options);
+}
+
+async function readPackageManifest(packageRoot) {
+  const manifest = JSON.parse(await readFile(join(packageRoot, "package.json"), "utf8"));
+  if (manifest.name !== name || !/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/u.test(manifest.version ?? "")) {
+    throw new Error("DeepSeek package manifest identity is invalid");
+  }
+  return manifest;
+}

package/lib/paths.mjs

@@ -0,0 +1,121 @@
+import { chmod, lstat, mkdir, realpath, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const DATA_DIRECTORY_ENVIRONMENT = "DEV_FLOW_DATA_DIR";
+
+export function packageRootFromModule(moduleUrl = import.meta.url) {
+  return dirname(dirname(fileURLToPath(moduleUrl)));
+}
+
+export async function resolveDataDirectory({
+  homeDirectory = homedir(),
+  environment = process.env,
+} = {}) {
+  const canonicalHome = await canonicalExistingDirectory(homeDirectory, "home directory");
+  const productSupportRoot = containedPath(
+    canonicalHome,
+    join(canonicalHome, "Library", "Application Support", "dev-flow"),
+    "product support root",
+  );
+
+  const explicitDataDirectory = environment?.[DATA_DIRECTORY_ENVIRONMENT] ?? "";
+  if (explicitDataDirectory !== "") {
+    const dataDirectory = await canonicalExplicitDataDirectory(explicitDataDirectory);
+    return Object.freeze({
+      dataDirectory,
+      homeDirectory: canonicalHome,
+      productSupportRoot,
+      usesDefaultDataDirectory: false,
+    });
+  }
+
+  await assertNoSymlinkComponents(canonicalHome, productSupportRoot);
+
+  return Object.freeze({
+    dataDirectory: containedPath(
+      productSupportRoot,
+      join(productSupportRoot, "data"),
+      "default data directory",
+    ),
+    homeDirectory: canonicalHome,
+    productSupportRoot,
+    usesDefaultDataDirectory: true,
+  });
+}
+
+export async function ensureDefaultDataDirectory(paths) {
+  if (!paths?.usesDefaultDataDirectory) {
+    throw new Error("refusing to create an explicit data directory");
+  }
+  const expected = containedPath(
+    paths.productSupportRoot,
+    join(paths.productSupportRoot, "data"),
+    "default data directory",
+  );
+  if (paths.dataDirectory !== expected) {
+    throw new Error("default data directory does not match the shared product path");
+  }
+
+  await assertNoSymlinkComponents(paths.homeDirectory, paths.productSupportRoot);
+  await mkdir(paths.dataDirectory, { recursive: true, mode: 0o700 });
+  await assertNoSymlinkComponents(paths.homeDirectory, paths.dataDirectory);
+  await chmod(paths.dataDirectory, 0o700);
+  return paths.dataDirectory;
+}
+
+export function containedPath(root, candidate, label = "path") {
+  const canonicalRoot = resolve(root);
+  const canonicalCandidate = resolve(candidate);
+  const offset = relative(canonicalRoot, canonicalCandidate);
+  if (offset === ".." || offset.startsWith(`..${sep}`) || isAbsolute(offset)) {
+    throw new Error(`${label} escapes its owned root`);
+  }
+  return canonicalCandidate;
+}
+
+async function canonicalExplicitDataDirectory(path) {
+  if (!isAbsolute(path)) {
+    throw new Error(`${DATA_DIRECTORY_ENVIRONMENT} must be an absolute path`);
+  }
+  const normalized = resolve(path);
+  const canonical = await canonicalExistingDirectory(path, DATA_DIRECTORY_ENVIRONMENT);
+  if (canonical !== normalized) {
+    throw new Error(`${DATA_DIRECTORY_ENVIRONMENT} must be canonical and may not use a symbolic link`);
+  }
+  return canonical;
+}
+
+async function canonicalExistingDirectory(path, label) {
+  if (!isAbsolute(path)) {
+    throw new Error(`${label} must be absolute`);
+  }
+  try {
+    const canonical = await realpath(path);
+    const info = await stat(canonical);
+    if (!info.isDirectory()) throw new Error("not a directory");
+    return canonical;
+  } catch (error) {
+    throw new Error(`${label} must name an existing directory`, { cause: error });
+  }
+}
+
+async function assertNoSymlinkComponents(root, candidate) {
+  const canonicalRoot = resolve(root);
+  const canonicalCandidate = containedPath(canonicalRoot, candidate, "product path");
+  const components = relative(canonicalRoot, canonicalCandidate).split(sep).filter(Boolean);
+  let current = canonicalRoot;
+  for (const component of components) {
+    current = join(current, component);
+    try {
+      const info = await lstat(current);
+      if (info.isSymbolicLink()) {
+        throw new Error(`product path contains a symbolic link: ${current}`);
+      }
+    } catch (error) {
+      if (error?.code === "ENOENT") return;
+      throw error;
+    }
+  }
+}