@nettoolskit/det 0.0.1-preview.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NetToolsKit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,253 @@
+# NetToolsKit DET
+
+> Semantic execution runtime for governed AI.
+
+---
+
+## Introduction
+
+DET — Decision, Execution & Traceability — is the NetToolsKit semantic
+execution runtime for governed AI. It orchestrates, optimizes, and governs AI
+task execution through meaning, memory, verification, and metacognitive
+control.
+
+DET coordinates AI models, MEVRA, Meaning Memory, tools, retrieval,
+verification, evaluation, policy, and metacognitive awareness so AI tasks can
+run with semantic grounding, traceability, safety, and measurable performance.
+It is not an agent framework and it does not own provider execution, memory
+storage, machine control, or downstream product orchestration.
+
+MEVRA proposes operational meaning. Meaning Memory validates and persists
+meaning. Metacognition monitors objective, focus, uncertainty, conflict, and
+risk. Verification validates. Anti-Deception protects. The LLM verbalizes. DET
+arbitrates and executes.
+
+---
+
+## Features
+
+- ✅ Semantic execution runtime for governed AI task planning and execution.
+- ✅ Decision, execution, verification, traceability, and policy arbitration contracts.
+- ✅ Meaning Memory integration boundaries for global, catalog, project-registry, and project-local memory layers.
+- ✅ Agent and Codegen consumption boundaries that avoid duplicating deterministic function implementations.
+- ✅ Operational `det run --task` dry-run entrypoint for governed route planning and traceability.
+- ✅ Harness-derived evidence, benchmark, and effectiveness contracts inside the DET workspace.
+- ✅ River-first validation model for Rust quality, package validation, and CI/CD governance.
+
+---
+
+## Contents
+
+- [Introduction](#introduction)
+- [Features](#features)
+- [Architecture](#architecture)
+    - [Architecture](#architecture-1)
+    - [Agentic Surfaces](#agentic-surfaces)
+- [Crates](#crates)
+- [Compatibility and Support](#compatibility-and-support)
+- [Operations](#operations)
+- [Planning](#planning)
+- [Governance and Security](#governance-and-security)
+- [Build and Tests](#build-and-tests)
+- [Contributing](#contributing)
+- [Dependencies](#dependencies)
+- [References](#references)
+- [License](#license)
+
+---
+
+## Architecture
+
+### Architecture
+
+```mermaid
+flowchart LR
+    User[Operator or host application] --> DET[DET runtime\nDecision, Execution & Traceability]
+    DET --> MEVRA[MEVRA\nMeaning proposal]
+    DET --> Memory[nettoolskit-memory\nMeaning Memory]
+    DET --> Agent[nettoolskit-agent\nDeterministic functions]
+    DET --> Codegen[nettoolskit-codegen\nComplex deterministic code architecture functions]
+    DET --> Analytics[nettoolskit-analytics\nEvaluation and effectiveness signals]
+    DET --> Harness[DET harness contracts\nEvidence and benchmark reproducibility]
+    DET --> Rust[nettoolskit-rust\nShared Rust foundation]
+    Copilot[nettoolskit-copilot] --> DET
+    Copilot --> Control[nettoolskit-control\nRemote machine control]
+```
+
+DET owns semantic arbitration, execution planning, traceability, governance,
+and verification boundaries. It consumes `nettoolskit-agent` and
+`nettoolskit-codegen` deterministic functions without duplicating their code.
+It integrates with `nettoolskit-memory` through Meaning Memory contracts and
+keeps storage, indexing, retrieval, and persistence in Memory.
+
+`nettoolskit-copilot` is a product surface that can use DET and remote control
+services. DET does not depend on Copilot or Control.
+
+### Agentic Surfaces
+
+DET uses agentic ecosystem components through explicit boundaries:
+
+- `nettoolskit-agent` owns canonical deterministic function catalogs,
+  commands, instruction contracts, and runtime guidance.
+- `nettoolskit-codegen` owns complex deterministic architecture/code-generation
+  functions that DET can select and orchestrate.
+- `nettoolskit-memory` owns Meaning Memory storage, retrieval, validation,
+  persistence, and project-local memory.
+- `nettoolskit-analytics` owns analytics and evaluation signals that DET can
+  use for measured effectiveness.
+- `nettoolskit-copilot` owns user-facing product orchestration and can call DET.
+- `nettoolskit-control` owns remote machine command execution and is not called
+  directly by DET.
+
+Detailed architecture is maintained in [ARCHITECTURE.md](ARCHITECTURE.md) and
+[docs/architecture-overview.md](docs/architecture-overview.md).
+
+---
+
+## Crates
+
+The DET workspace is organized by owned crates under `crates/*`.
+
+| Crate | Purpose | README |
+| --- | --- | --- |
+| `agentic-rag` | Agentic RAG planning and policy contracts. | [README](crates/agentic-rag/README.md) |
+| `cli` | Public CLI and compatibility facade. | [README](crates/cli/README.md) |
+| `core` | Core semantic execution and repository profile contracts. | [README](crates/core/README.md) |
+| `harness` | Harness-derived evidence and reproducibility contracts. | [README](crates/harness/README.md) |
+| `integrations` | Agent, Memory, analytics, and ecosystem integration boundaries. | [README](crates/integrations/README.md) |
+| `language` | DET language parsing and runtime-language contracts. | [README](crates/language/README.md) |
+| `runtime` | Runtime admission, DET home, wrapper, benchmark, and registry contracts. | [README](crates/runtime/README.md) |
+
+---
+
+## Compatibility and Support
+
+DET is in MVP implementation and should be consumed through committed Rust
+contracts, documented CLI surfaces, and explicit JSON request/response shapes.
+Distribution targets npm/npx, Docker, GitHub Releases, and Winget; Cargo
+publication is not the preferred operator install path for this product stage.
+
+Supported operator paths and release-readiness details live in
+[docs/install.md](docs/install.md), [docs/release.md](docs/release.md).
+
+---
+
+## Operations
+
+Operational details are intentionally kept out of the root README:
+
+- Basic usage: [docs/getting-started/basic-usage.md](docs/getting-started/basic-usage.md)
+- Operational task runtime: `det run --task --json <run-task-request.json>`
+- DET home and Meaning Memory layers: [docs/det-home-memory.md](docs/det-home-memory.md)
+- Local validation and CI/CD routing: [docs/operations/local-validation.md](docs/operations/local-validation.md)
+- River CI policy: [docs/operations/river-ci.md](docs/operations/river-ci.md)
+- Runtime wrapper: [docs/runtime-wrapper.md](docs/runtime-wrapper.md)
+- Benchmark evidence: [docs/local-det-vs-baseline-benchmark.md](docs/local-det-vs-baseline-benchmark.md)
+- Guarded DET dogfood with Agent and Meaning Memory: [docs/guarded-det-dogfood.md](docs/guarded-det-dogfood.md)
+
+---
+
+## Planning
+
+Planning state is kept under `planning/` and should remain tied to concrete
+workstreams, validation evidence, and PR closeout.
+
+Useful entry points:
+
+- [Planning index](planning/README.md)
+- [Active DET semantic execution spec](planning/specs/active/202605272037-spec-nettoolskit-det-semantic-execution-engine.md)
+- [Memory and model evaluation plan](planning/plans/completed/2026-06/202606081130-plan-det-memory-as-model-evaluation.md)
+- [Benchmark artifact manifest plan](planning/plans/completed/2026-06/202606091205-plan-det-benchmark-artifact-manifest.md)
+
+---
+
+## Governance and Security
+
+DET keeps execution ownership explicit:
+
+- DET arbitrates and plans; it does not duplicate provider, Agent, Codegen,
+  Memory, Control, Copilot, DevOps, Assurance, or Analytics implementation code.
+- Memory owns retrieval, validation, persistence, indexing, and storage.
+- Agent owns deterministic function catalogs and command contracts.
+- Codegen owns complex deterministic architecture/code-generation functions.
+- Control owns remote machine command execution and is not a DET dependency.
+- Provider calls, MCP invocation, shell execution, persistence, and runtime IO
+  require explicit host-owned boundaries.
+
+See [docs/det-ecosystem-ownership-model.md](docs/det-ecosystem-ownership-model.md)
+and [docs/ci-gitriver.md](docs/ci-gitriver.md) for the detailed governance
+model.
+
+---
+
+## Build and Tests
+
+Local validation should mirror the River Rust quality gate:
+
+```powershell
+cargo fmt --all --check
+cargo test --all-targets --locked
+cargo clippy --all-targets --locked -- -D warnings
+cargo doc --no-deps --locked
+git diff --check
+```
+
+Package/security validation is separate from Rust quality. PR runs should keep
+package security bounded by auditing dependencies, building docs, listing Cargo
+package contents, and generating allowlisted tarballs without repeating full
+workspace package verification. Full Cargo package verification is reserved for
+explicit release or manual proof.
+
+The source-owned River validation path is documented in
+[docs/operations/local-validation.md](docs/operations/local-validation.md) and
+[docs/operations/river-ci.md](docs/operations/river-ci.md).
+
+---
+
+## Contributing
+
+Use a dedicated branch or worktree for each change-bearing workstream. Keep
+changes scoped to the active plan, update README/manifest/changelog only when
+the implemented behavior changes, and record validation evidence before opening
+or updating a pull request.
+
+Every completed workstream should leave the local worktree clean, planning
+state updated, and validation results reproducible from committed source.
+
+---
+
+## Dependencies
+
+Runtime dependencies are intentionally small:
+
+| Dependency | Purpose |
+| --- | --- |
+| `serde` | Public contract serialization and deserialization. |
+| `serde_json` | JSON registry, manifest, and test serialization support. |
+
+Development and validation depend on the Rust toolchain, Cargo, `cargo audit`,
+and Git.
+
+---
+
+## References
+
+- [Changelog](CHANGELOG.md)
+- [Architecture](ARCHITECTURE.md)
+- [Documentation index](docs/README.md)
+- [Planning](planning/README.md)
+- [Service manifest](nettoolskit.manifest.json)
+- [River CI gates](scripts/ci/river/README.md)
+- [GitHub repository](https://github.com/NetToolsKit/nettoolskit-det)
+- [Apache DataFusion Query Optimizer](https://datafusion.apache.org/library-user-guide/query-optimizer.html)
+- [Qdrant Indexing](https://qdrant.tech/documentation/concepts/indexing/)
+- [OpenTelemetry](https://opentelemetry.io/docs/)
+
+---
+
+## License
+
+This project is licensed under the MIT License. See the LICENSE file at the
+repository root for details.
+
+---

package/npm/cli/det.js

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+
+const { spawnSync } = require("node:child_process");
+const fs = require("node:fs");
+const path = require("node:path");
+const { initializeRuntimeHome } = require("../runtime/bootstrap");
+
+const repoRoot = path.resolve(__dirname, "..", "..");
+const nativeName = process.platform === "win32" ? "det.exe" : "det";
+const bundledBinary = path.join(repoRoot, "npm", "native", nativeName);
+const explicitBinary = process.env.NTK_DET_BINARY || process.env.NETTOOLSKIT_DET_BINARY;
+
+try {
+  initializeRuntimeHome();
+} catch (error) {
+  console.error(`DET runtime bootstrap failed: ${error.message}`);
+  process.exit(126);
+}
+
+function executableExists(candidate) {
+  return Boolean(candidate) && fs.existsSync(candidate);
+}
+
+function failMissingBinary(detail) {
+  console.error("DET binary was not found.");
+  if (detail) {
+    console.error(detail);
+  }
+  console.error("Set NTK_DET_BINARY to a GitHub Release binary or reinstall @nettoolskit/det.");
+  process.exit(127);
+}
+
+let binary;
+if (explicitBinary) {
+  if (!executableExists(explicitBinary)) {
+    failMissingBinary(`Configured DET binary does not exist: ${explicitBinary}`);
+  }
+  binary = explicitBinary;
+} else if (executableExists(bundledBinary)) {
+  binary = bundledBinary;
+} else {
+  failMissingBinary(`Expected bundled binary at: ${bundledBinary}`);
+}
+
+const executableBinary = process.platform === "win32" ? path.toNamespacedPath(binary) : binary;
+const result = spawnSync(executableBinary, process.argv.slice(2), {
+  stdio: "inherit",
+  windowsHide: true,
+});
+
+if (result.error) {
+  failMissingBinary(result.error.message);
+}
+
+if (typeof result.status === "number") {
+  process.exit(result.status);
+}
+
+process.exit(1);

package/npm/runtime/bootstrap.js

@@ -0,0 +1,135 @@
+"use strict";
+
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+
+const SCHEMA_VERSION = "det.runtime_install_bootstrap.v1";
+const DET_HOME_DIR_NAME = ".det";
+const MEMORY_DIR_NAME = "memory";
+const PROJECT_MEMORY_DIR = path.join(".det", "project-memory");
+const SKIP_ENV_VARS = [
+  "NETTOOLSKIT_DET_SKIP_RUNTIME_BOOTSTRAP",
+  "NTK_DET_SKIP_RUNTIME_BOOTSTRAP",
+];
+
+function shouldSkipRuntimeBootstrap(env = process.env) {
+  return SKIP_ENV_VARS.some((name) => env[name] === "1" || env[name] === "true");
+}
+
+function initializeRuntimeHome(options = {}) {
+  const env = options.env || process.env;
+
+  if (options.allowSkip !== false && shouldSkipRuntimeBootstrap(env)) {
+    return {
+      schemaVersion: SCHEMA_VERSION,
+      status: "skipped",
+      skipped: true,
+      reason: "runtime bootstrap disabled by environment",
+    };
+  }
+
+  const detHome = resolveDetHome(options.detHome || env.DET_HOME);
+  assertSafeRuntimePath(detHome, "DET_HOME");
+
+  const memoryRoot = path.join(detHome, MEMORY_DIR_NAME);
+  const memoryLayers = [
+    layer("global", path.join(memoryRoot, "global")),
+    layer("global_catalogs", path.join(memoryRoot, "catalogs")),
+    layer("global_projects", path.join(memoryRoot, "projects")),
+  ];
+
+  ensureDirectory(detHome);
+  ensureDirectory(memoryRoot);
+  for (const memoryLayer of memoryLayers) {
+    ensureDirectory(memoryLayer.path);
+  }
+
+  let projectMemory = null;
+  const projectRoot = options.projectRoot || env.DET_PROJECT_ROOT;
+  if (projectRoot) {
+    const resolvedProjectRoot = path.resolve(projectRoot);
+    assertSafeRuntimePath(resolvedProjectRoot, "DET_PROJECT_ROOT");
+    projectMemory = path.join(resolvedProjectRoot, PROJECT_MEMORY_DIR);
+    ensureDirectory(projectMemory);
+  }
+
+  const report = {
+    schemaVersion: SCHEMA_VERSION,
+    status: "ready",
+    detHome,
+    memoryRoot,
+    memoryLayers,
+    projectMemory,
+    memoryExecutable: env.DET_NTK_MEMORY_EXECUTABLE || "ntk-memory",
+    storageOwner: "nettoolskit-memory",
+    createdBy: "@nettoolskit/det",
+    writesProviderPayloads: false,
+    writesSecrets: false,
+    mutatesShellProfiles: false,
+  };
+
+  if (options.writeState !== false) {
+    fs.writeFileSync(
+      path.join(detHome, "install-state.json"),
+      `${JSON.stringify(report, null, 2)}\n`,
+      "utf8",
+    );
+  }
+
+  return report;
+}
+
+function resolveDetHome(configuredHome) {
+  if (configuredHome && configuredHome.trim()) {
+    return path.resolve(configuredHome.trim());
+  }
+
+  const home = os.homedir();
+  if (!home) {
+    throw new Error("DET_HOME could not be resolved because the user home directory is unavailable");
+  }
+
+  return path.join(home, DET_HOME_DIR_NAME);
+}
+
+function layer(scope, layerPath) {
+  return {
+    scope,
+    path: layerPath,
+    global: true,
+    projectLocal: false,
+    versioned: false,
+  };
+}
+
+function ensureDirectory(directory) {
+  fs.mkdirSync(directory, { recursive: true });
+}
+
+function assertSafeRuntimePath(candidate, label) {
+  const normalized = candidate.replace(/\\/g, "/").toLowerCase();
+  if (
+    !normalized ||
+    normalized.includes("/../") ||
+    normalized.endsWith("/..") ||
+    normalized.startsWith("../") ||
+    normalized.includes("raw_prompt") ||
+    normalized.includes("provider_payload") ||
+    normalized.includes("secret") ||
+    normalized.includes("token")
+  ) {
+    throw new Error(`${label} is not safe for DET runtime bootstrap`);
+  }
+}
+
+if (require.main === module) {
+  const report = initializeRuntimeHome();
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+}
+
+module.exports = {
+  SCHEMA_VERSION,
+  initializeRuntimeHome,
+  shouldSkipRuntimeBootstrap,
+};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@nettoolskit/det",
+  "version": "0.0.1-preview.1",
+  "description": "NetToolsKit DET command-line wrapper.",
+  "license": "MIT",
+  "keywords": [
+    "nettoolskit",
+    "det",
+    "cli",
+    "semantic-runtime"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/NetToolsKit/nettoolskit-det.git"
+  },
+  "homepage": "https://github.com/NetToolsKit/nettoolskit-det#readme",
+  "bugs": {
+    "url": "https://github.com/NetToolsKit/nettoolskit-det/issues"
+  },
+  "bin": {
+    "det": "npm/cli/det.js",
+    "ntk-det": "npm/cli/det.js"
+  },
+  "files": [
+    "LICENSE",
+    "README.md",
+    "npm/cli/det.js",
+    "npm/native/",
+    "npm/runtime/bootstrap.js",
+    "scripts/npm/postinstall.js"
+  ],
+  "scripts": {
+    "test:postinstall-integrity": "node scripts/npm/test-postinstall-integrity.js",
+    "postinstall": "node scripts/npm/postinstall.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/scripts/npm/postinstall.js

@@ -0,0 +1,211 @@
+#!/usr/bin/env node
+
+const crypto = require("node:crypto");
+const fs = require("node:fs");
+const path = require("node:path");
+
+const packageJson = require("../../package.json");
+const { initializeRuntimeHome } = require("../../npm/runtime/bootstrap");
+const metadataAsset = "det-distribution-artifact-metadata.json";
+
+class DetBinaryIntegrityError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "DetBinaryIntegrityError";
+  }
+}
+
+if (require.main === module) {
+  main().catch(handlePostinstallFailure);
+}
+
+async function main() {
+  try {
+    initializeRuntimeHome();
+  } catch (error) {
+    console.warn(`DET runtime bootstrap failed: ${error.message}`);
+    process.exit(1);
+  }
+
+  if (process.env.NETTOOLSKIT_DET_SKIP_DOWNLOAD === "1" || process.env.NTK_DET_SKIP_DOWNLOAD === "1") {
+    return;
+  }
+
+  const target = releaseTarget();
+  if (target && target.unsupported) {
+    console.warn(target.message);
+    console.warn("Use Docker, a Windows/Linux GitHub Release binary, or set NTK_DET_BINARY to a compatible locally built binary.");
+    return;
+  }
+  if (!target) {
+    console.warn(`No DET GitHub Release binary is declared for ${process.platform}/${process.arch}.`);
+    console.warn("Set NTK_DET_BINARY to a local binary before running det.");
+    return;
+  }
+
+  const nativeDir = path.resolve(__dirname, "..", "..", "npm", "native");
+  const binaryPath = path.join(nativeDir, process.platform === "win32" ? "det.exe" : "det");
+  const releaseVersion = `v${packageJson.version}`;
+  fs.mkdirSync(nativeDir, { recursive: true });
+
+  const expectedSha256 = await resolveExpectedSha256(releaseVersion, target.asset);
+
+  if (fs.existsSync(binaryPath)) {
+    const existingSha256 = sha256File(binaryPath);
+    if (existingSha256 === expectedSha256) {
+      if (process.platform !== "win32") {
+        fs.chmodSync(binaryPath, 0o755);
+      }
+      return;
+    }
+    fs.rmSync(binaryPath, { force: true });
+    console.warn("Existing DET binary was removed because release checksum verification failed.");
+  }
+
+  const url = `https://github.com/NetToolsKit/nettoolskit-det/releases/download/${releaseVersion}/${target.asset}`;
+
+  await downloadVerified(url, binaryPath, expectedSha256);
+}
+
+async function download(url, destination) {
+  assertTrustedReleaseUrl(url);
+  const timeoutMs = Number.parseInt(process.env.NTK_DET_DOWNLOAD_TIMEOUT_MS || "120000", 10);
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+  const temporaryDestination = `${destination}.tmp-${process.pid}`;
+
+  try {
+    const response = await fetch(url, { redirect: "follow", signal: controller.signal });
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}`);
+    }
+
+    const body = Buffer.from(await response.arrayBuffer());
+    fs.writeFileSync(temporaryDestination, body);
+    fs.renameSync(temporaryDestination, destination);
+    if (process.platform !== "win32") {
+      fs.chmodSync(destination, 0o755);
+    }
+  } finally {
+    clearTimeout(timeout);
+    fs.rmSync(temporaryDestination, { force: true });
+  }
+}
+
+async function downloadVerified(url, destination, expectedSha256) {
+  await download(url, destination);
+  const actualSha256 = sha256File(destination);
+
+  if (actualSha256 !== expectedSha256) {
+    fs.rmSync(destination, { force: true });
+    throw new DetBinaryIntegrityError(
+      `DET binary checksum mismatch for ${path.basename(destination)}; expected ${expectedSha256}, got ${actualSha256}`
+    );
+  }
+}
+
+async function resolveExpectedSha256(releaseVersion, assetName) {
+  const metadataUrl = `https://github.com/NetToolsKit/nettoolskit-det/releases/download/${releaseVersion}/${metadataAsset}`;
+  const metadata = await downloadJson(metadataUrl);
+  return findReleaseAssetSha256(metadata, releaseVersion, assetName);
+}
+
+async function downloadJson(url) {
+  const temporaryDestination = path.join(
+    path.resolve(__dirname, "..", "..", "npm", "native"),
+    `${metadataAsset}.tmp-${process.pid}`
+  );
+
+  await download(url, temporaryDestination);
+
+  try {
+    return JSON.parse(fs.readFileSync(temporaryDestination, "utf8"));
+  } catch (error) {
+    throw new DetBinaryIntegrityError(`Invalid DET release metadata JSON: ${error.message}`);
+  } finally {
+    fs.rmSync(temporaryDestination, { force: true });
+  }
+}
+
+function findReleaseAssetSha256(metadata, releaseVersion, assetName) {
+  if (!metadata || typeof metadata !== "object") {
+    throw new DetBinaryIntegrityError("DET release metadata is empty or invalid.");
+  }
+
+  if (metadata.releaseTag !== releaseVersion) {
+    throw new DetBinaryIntegrityError(
+      `DET release metadata tag mismatch; expected ${releaseVersion}, got ${metadata.releaseTag || "<missing>"}`
+    );
+  }
+
+  const channels = Array.isArray(metadata.channels) ? metadata.channels : [];
+  const githubRelease = channels.find((channel) => channel && channel.id === "github_release_binary");
+
+  if (!githubRelease || !Array.isArray(githubRelease.assets)) {
+    throw new DetBinaryIntegrityError("DET release metadata does not contain github_release_binary assets.");
+  }
+
+  const asset = githubRelease.assets.find((candidate) => candidate && candidate.name === assetName);
+  if (!asset || typeof asset.sha256 !== "string") {
+    throw new DetBinaryIntegrityError(`DET release metadata does not contain SHA-256 for ${assetName}.`);
+  }
+
+  const sha256 = asset.sha256.toLowerCase();
+  if (!/^[a-f0-9]{64}$/.test(sha256)) {
+    throw new DetBinaryIntegrityError(`DET release metadata contains an invalid SHA-256 for ${assetName}.`);
+  }
+
+  return sha256;
+}
+
+function assertTrustedReleaseUrl(url) {
+  const parsed = new URL(url);
+  if (parsed.protocol !== "https:" || parsed.hostname !== "github.com") {
+    throw new DetBinaryIntegrityError(`Untrusted DET release URL: ${url}`);
+  }
+}
+
+function sha256File(filePath) {
+  return sha256Buffer(fs.readFileSync(filePath));
+}
+
+function sha256Buffer(buffer) {
+  return crypto.createHash("sha256").update(buffer).digest("hex");
+}
+
+function handlePostinstallFailure(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  console.warn(`DET binary download failed: ${message}`);
+  console.warn("Set NTK_DET_BINARY to a local binary or install from a GitHub Release asset.");
+
+  if (error instanceof DetBinaryIntegrityError) {
+    process.exitCode = 1;
+  }
+}
+
+function releaseTarget() {
+  const platform = process.platform;
+  const arch = process.arch;
+
+  if (platform === "win32" && arch === "x64") {
+    return { asset: "det-x86_64-pc-windows-msvc.exe" };
+  }
+  if (platform === "linux" && arch === "x64") {
+    return { asset: "det-x86_64-unknown-linux-gnu" };
+  }
+  if (platform === "darwin") {
+    return {
+      unsupported: true,
+      message: `macOS GitHub Release binary assets are pending for DET v${packageJson.version}.`,
+    };
+  }
+
+  return null;
+}
+
+module.exports = {
+  DetBinaryIntegrityError,
+  findReleaseAssetSha256,
+  releaseTarget,
+  sha256Buffer,
+};