wireforge 0.1.0__tar.gz

wireforge-0.1.0/LICENSE

@@ -0,0 +1,98 @@
+Business Source License 1.1
+
+Parameters
+
+Licensor:             Oguzhan KAYNAK
+Licensed Work:        WireForge (this repository), excluding the contents of the
+                      `runtime/` directory, which are separately licensed under
+                      the MIT License (see runtime/LICENSE). The Licensed Work
+                      is (c) 2026 Oguzhan KAYNAK.
+Additional Use Grant: You may use the Licensed Work for development, testing,
+                      evaluation, and other non-production purposes free of
+                      charge. Any production use of the Licensed Work requires
+                      a commercial license from the Licensor.
+Change Date:          2036-10-17
+Change License:       MIT
+
+For information about alternative licensing arrangements for the Licensed Work,
+please contact the Licensor.
+
+Notice
+
+The Business Source License (this document, or the "License") is not an Open
+Source license. However, the Licensed Work will eventually be made available
+under an Open Source License, as stated in this License.
+
+License text copyright (c) 2017 MariaDB Corporation Ab, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB Corporation Ab.
+
+-----------------------------------------------------------------------------
+
+Business Source License 1.1
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited
+production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.
+
+MariaDB hereby grants you permission to use this License's text to license
+your works, and to refer to it using the trademark "Business Source License",
+as long as you comply with the Covenants of Licensor below.
+
+Covenants of Licensor
+
+In consideration of the right to use this License's text and the "Business
+Source License" name and trademark, Licensor covenants to MariaDB, and to all
+other recipients of the licensed work to be provided by Licensor:
+
+1. To specify as the Change License the GPL Version 2.0 or any later version,
+   or a license that is compatible with GPL Version 2.0 or a later version,
+   where "compatible" means that software provided under the Change License
+   can be included in a program with software provided under GPL Version 2.0
+   or a later version. Licensor may specify additional Change Licenses
+   without limitation.
+
+2. To either: (a) specify an additional grant of rights to use that does not
+   impose any additional restriction on the right granted in this License, as
+   the Additional Use Grant; or (b) insert the text "None".
+
+3. To specify a Change Date.
+
+4. Not to modify this License in any other way.

wireforge-0.1.0/MANIFEST.in

@@ -0,0 +1,8 @@
+# What the source distribution carries so that a wheel can be built from it (setup.py copies these
+# directories into the wheel).
+include LICENSE README.md
+include runtime/LICENSE runtime/requirements.yaml
+recursive-include schema *.json
+recursive-include runtime/include *.hpp
+recursive-include cmake/package *
+recursive-include ui/dist *

wireforge-0.1.0/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: wireforge
+Version: 0.1.0
+Summary: Schema-driven wire-format toolkit: C++17 code generation, validation, server and MCP.
+Author: Oguzhan KAYNAK
+License-Expression: BUSL-1.1 AND MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: runtime/LICENSE
+Requires-Dist: ruamel.yaml>=0.18
+Requires-Dist: jsonschema>=4.21
+Requires-Dist: referencing>=0.30
+Requires-Dist: typing_extensions>=4.4
+Provides-Extra: server
+Requires-Dist: fastapi>=0.110; extra == "server"
+Requires-Dist: uvicorn>=0.29; extra == "server"
+Provides-Extra: oidc
+Requires-Dist: joserfc>=1.0; extra == "oidc"
+Provides-Extra: mcp
+Requires-Dist: mcp>=2.3; extra == "mcp"
+Provides-Extra: import
+Requires-Dist: openpyxl>=3.1; extra == "import"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff<0.18,>=0.17; extra == "dev"
+Requires-Dist: mypy<3,>=2.4; extra == "dev"
+Requires-Dist: types-jsonschema; extra == "dev"
+Requires-Dist: gcovr>=7; extra == "dev"
+Requires-Dist: clang-tidy==18.1.8; extra == "dev"
+Requires-Dist: fastapi>=0.110; extra == "dev"
+Requires-Dist: uvicorn>=0.29; extra == "dev"
+Requires-Dist: httpx2>=2.13; extra == "dev"
+Requires-Dist: mcp>=2.3; extra == "dev"
+Requires-Dist: openpyxl>=3.1; extra == "dev"
+Requires-Dist: joserfc>=1.0; extra == "dev"
+Requires-Dist: types-openpyxl; extra == "dev"
+Requires-Dist: pymodbus==3.16.1; extra == "dev"
+Dynamic: license-file
+
+# WireForge
+
+Schema-driven wire-format toolkit for C++17: describe binary messages in YAML (by hand, in the web UI, through the CLI
+or an AI agent) and generate allocation-free C++ serializers, validators, framers and dispatchers together with a
+GoogleTest project that proves them against a reference codec and gates the generated code at 100 % line, branch and
+function coverage.
+
+- The wire format is imposed by the remote party: generated code never adds bytes.
+- Runtime and generated code use only pre-allocated storage: no heap, no exceptions, no RTTI required.
+- One service layer behind the `wireforge` CLI, the Python API, the REST server with its web UI and the MCP server.
+- A generated Wireshark Lua dissector shows every interface's frames, with the same checks as the decoder.
+- Zero warnings from every compiler and analyzer; tested on 32/64 bit, little and big endian, x86 and ARM, on Linux,
+  Windows, macOS, Android and FreeRTOS; differential testing and fuzzing.
+
+The way in is short: `wireforge init` gives a working first project, you change it to your protocol, generate the C++
+code, run the tests and read the results. Nothing about requirements or standards is needed for that.
+
+## For teams with a development or assurance process
+Optionally, `wireforge docs` turns the same model into requirements, design, test and traceability documents with test
+and coverage results, change impact between revisions and ReqIF/CSV exchange with requirements tools (docs/LIFECYCLE.md,
+docs/integration/). For projects that apply standards such as DO-178C, ISO 26262, IEC 61508 or IEC 62304, this evidence
+supports your processes and your tool assessment; it does not by itself give conformity, certification or tool
+qualification, which depend on the whole project and its assessor (docs/DO178C.md).
+
+**Start with docs/GUIDE.md** (install, 5-minute quickstart, examples). Reference:
+
+| Topic | Document |
+|-------|----------|
+| Definition format | docs/SCHEMA_SPEC.md, `schema/`, `examples/` |
+| Command line and Python API | docs/CLI.md |
+| Generated C++ and test project | docs/CODEGEN.md, docs/RUNTIME.md |
+| Layout analysis / ICD export | docs/LAYOUT.md |
+| Wireshark dissector (Lua plugin) | docs/WIRESHARK.md |
+| Requirements, design and test documents | docs/LIFECYCLE.md |
+| Fitting into a DO-178C process, tool integration | docs/DO178C.md, docs/integration/ |
+| Server, web UI, MCP | docs/SERVER.md, docs/UI.md, docs/MCP.md |
+| Secure deployment and operation | docs/SERVER.md, "Deployment and operation" |
+| Importers (CSV/Excel ICD, C headers) | docs/IMPORT.md |
+| Quality, safety, traceability | quality/QUALITY_POLICY.md, docs/SAFETY.md, docs/CODING_RULES.md |
+| Architecture and design decisions | docs/ARCHITECTURE.md, docs/DECISIONS.md |
+
+Development: see CONTRIBUTING.md (`pip install -e ".[dev]"`, `cmake --preset dev && cmake --build --preset dev && ctest
+--preset dev`, all gates: `quality/run_all.sh`).
+
+## License
+The `runtime/` library is MIT-licensed (see runtime/LICENSE): code generated by WireForge belongs to you and depends
+only on this MIT-licensed runtime, so shipping it in your product carries no restriction.
+
+Everything else (the CLI, code generator, server, web UI, and MCP server) is licensed under the Business Source
+License 1.1 (see LICENSE): free for development, testing, and evaluation; a commercial license is required for
+production use. It converts to MIT on 2036-10-17. Contact the Licensor for commercial licensing.

wireforge-0.1.0/README.md

@@ -0,0 +1,51 @@
+# WireForge
+
+Schema-driven wire-format toolkit for C++17: describe binary messages in YAML (by hand, in the web UI, through the CLI
+or an AI agent) and generate allocation-free C++ serializers, validators, framers and dispatchers together with a
+GoogleTest project that proves them against a reference codec and gates the generated code at 100 % line, branch and
+function coverage.
+
+- The wire format is imposed by the remote party: generated code never adds bytes.
+- Runtime and generated code use only pre-allocated storage: no heap, no exceptions, no RTTI required.
+- One service layer behind the `wireforge` CLI, the Python API, the REST server with its web UI and the MCP server.
+- A generated Wireshark Lua dissector shows every interface's frames, with the same checks as the decoder.
+- Zero warnings from every compiler and analyzer; tested on 32/64 bit, little and big endian, x86 and ARM, on Linux,
+  Windows, macOS, Android and FreeRTOS; differential testing and fuzzing.
+
+The way in is short: `wireforge init` gives a working first project, you change it to your protocol, generate the C++
+code, run the tests and read the results. Nothing about requirements or standards is needed for that.
+
+## For teams with a development or assurance process
+Optionally, `wireforge docs` turns the same model into requirements, design, test and traceability documents with test
+and coverage results, change impact between revisions and ReqIF/CSV exchange with requirements tools (docs/LIFECYCLE.md,
+docs/integration/). For projects that apply standards such as DO-178C, ISO 26262, IEC 61508 or IEC 62304, this evidence
+supports your processes and your tool assessment; it does not by itself give conformity, certification or tool
+qualification, which depend on the whole project and its assessor (docs/DO178C.md).
+
+**Start with docs/GUIDE.md** (install, 5-minute quickstart, examples). Reference:
+
+| Topic | Document |
+|-------|----------|
+| Definition format | docs/SCHEMA_SPEC.md, `schema/`, `examples/` |
+| Command line and Python API | docs/CLI.md |
+| Generated C++ and test project | docs/CODEGEN.md, docs/RUNTIME.md |
+| Layout analysis / ICD export | docs/LAYOUT.md |
+| Wireshark dissector (Lua plugin) | docs/WIRESHARK.md |
+| Requirements, design and test documents | docs/LIFECYCLE.md |
+| Fitting into a DO-178C process, tool integration | docs/DO178C.md, docs/integration/ |
+| Server, web UI, MCP | docs/SERVER.md, docs/UI.md, docs/MCP.md |
+| Secure deployment and operation | docs/SERVER.md, "Deployment and operation" |
+| Importers (CSV/Excel ICD, C headers) | docs/IMPORT.md |
+| Quality, safety, traceability | quality/QUALITY_POLICY.md, docs/SAFETY.md, docs/CODING_RULES.md |
+| Architecture and design decisions | docs/ARCHITECTURE.md, docs/DECISIONS.md |
+
+Development: see CONTRIBUTING.md (`pip install -e ".[dev]"`, `cmake --preset dev && cmake --build --preset dev && ctest
+--preset dev`, all gates: `quality/run_all.sh`).
+
+## License
+The `runtime/` library is MIT-licensed (see runtime/LICENSE): code generated by WireForge belongs to you and depends
+only on this MIT-licensed runtime, so shipping it in your product carries no restriction.
+
+Everything else (the CLI, code generator, server, web UI, and MCP server) is licensed under the Business Source
+License 1.1 (see LICENSE): free for development, testing, and evaluation; a commercial license is required for
+production use. It converts to MIT on 2036-10-17. Contact the Licensor for commercial licensing.

wireforge-0.1.0/cmake/package/WireForgeConfig.cmake

@@ -0,0 +1,29 @@
+# CMake package of WireForge: find_package(WireForge) gives
+#  - wireforge::runtime: the header-only C++17 runtime;
+#  - wireforge_generate(): generates C++ code from a WireForge project at configure time.
+# Works from an installed tree (<prefix>/lib/cmake/WireForge) and from the Python package
+# (`wireforge cmake-dir` prints this directory).
+include_guard(GLOBAL)
+
+set(WIREFORGE_INCLUDE_DIR "")
+foreach(candidate "${CMAKE_CURRENT_LIST_DIR}/../runtime/include" "${CMAKE_CURRENT_LIST_DIR}/../../../include"
+        "${CMAKE_CURRENT_LIST_DIR}/../../runtime/include")
+  if(NOT WIREFORGE_INCLUDE_DIR AND EXISTS "${candidate}/wireforge/status.hpp")
+    get_filename_component(WIREFORGE_INCLUDE_DIR "${candidate}" ABSOLUTE)
+  endif()
+endforeach()
+if(NOT WIREFORGE_INCLUDE_DIR)
+  set(WireForge_FOUND FALSE)
+  set(WireForge_NOT_FOUND_MESSAGE "the WireForge runtime headers were not found next to ${CMAKE_CURRENT_LIST_DIR}")
+  return()
+endif()
+
+if(NOT TARGET wireforge::runtime)
+  add_library(wireforge::runtime INTERFACE IMPORTED)
+  set_target_properties(wireforge::runtime PROPERTIES
+    INTERFACE_INCLUDE_DIRECTORIES "${WIREFORGE_INCLUDE_DIR}"
+    INTERFACE_COMPILE_FEATURES cxx_std_17)
+endif()
+
+include("${CMAKE_CURRENT_LIST_DIR}/WireForgeGenerate.cmake")
+set(WireForge_FOUND TRUE)

wireforge-0.1.0/cmake/package/WireForgeConfigVersion.cmake

@@ -0,0 +1,15 @@
+# Version of the WireForge CMake package; compatible within the same major version.
+set(PACKAGE_VERSION "0.1.0")
+if(PACKAGE_FIND_VERSION VERSION_GREATER PACKAGE_VERSION)
+  set(PACKAGE_VERSION_COMPATIBLE FALSE)
+else()
+  string(REGEX MATCH "^[0-9]+" _wireforge_major "${PACKAGE_VERSION}")
+  if(PACKAGE_FIND_VERSION_MAJOR STREQUAL "" OR PACKAGE_FIND_VERSION_MAJOR STREQUAL _wireforge_major)
+    set(PACKAGE_VERSION_COMPATIBLE TRUE)
+  else()
+    set(PACKAGE_VERSION_COMPATIBLE FALSE)
+  endif()
+  if(PACKAGE_FIND_VERSION STREQUAL PACKAGE_VERSION)
+    set(PACKAGE_VERSION_EXACT TRUE)
+  endif()
+endif()

wireforge-0.1.0/cmake/package/WireForgeGenerate.cmake

@@ -0,0 +1,64 @@
+# wireforge_generate(<target> PROJECT <dir> [OUTPUT <dir>] [PLUGINS <file>] [TESTS])
+#
+# Runs `wireforge generate` at configure time (again whenever a model file changes) and creates
+# the INTERFACE library <target> with the generated headers, the project's user include
+# directories and wireforge::runtime. With TESTS the GoogleTest project is generated too
+# (<OUTPUT>/<project>/generated_tests). The generator is the `wireforge` command, or
+# `python -m wireforge.cli` when only the Python package is found (WIREFORGE_COMMAND overrides).
+include_guard(GLOBAL)
+
+function(_wireforge_command result)
+  if(WIREFORGE_COMMAND)
+    set(${result} ${WIREFORGE_COMMAND} PARENT_SCOPE)
+    return()
+  endif()
+  find_program(WIREFORGE_EXECUTABLE wireforge)
+  if(WIREFORGE_EXECUTABLE)
+    set(${result} "${WIREFORGE_EXECUTABLE}" PARENT_SCOPE)
+    return()
+  endif()
+  find_package(Python3 REQUIRED COMPONENTS Interpreter)
+  set(${result} "${Python3_EXECUTABLE}" -m wireforge.cli PARENT_SCOPE)
+endfunction()
+
+function(wireforge_generate target)
+  cmake_parse_arguments(PARSE_ARGV 1 arg "TESTS" "PROJECT;OUTPUT;PLUGINS" "")
+  if(NOT arg_PROJECT)
+    message(FATAL_ERROR "wireforge_generate(${target}): PROJECT is required")
+  endif()
+  get_filename_component(project "${arg_PROJECT}" ABSOLUTE)
+  set(output "${CMAKE_CURRENT_BINARY_DIR}/wireforge_${target}")
+  if(arg_OUTPUT)
+    get_filename_component(output "${arg_OUTPUT}" ABSOLUTE)
+  endif()
+  _wireforge_command(command)
+  set(arguments generate "${project}" -o "${output}")
+  if(arg_TESTS)
+    list(APPEND arguments --tests)
+  endif()
+  if(arg_PLUGINS)
+    list(APPEND arguments --plugins "${arg_PLUGINS}")
+  endif()
+  execute_process(COMMAND ${command} ${arguments} RESULT_VARIABLE failed OUTPUT_VARIABLE log ERROR_VARIABLE log)
+  if(failed)
+    message(FATAL_ERROR "wireforge_generate(${target}) failed:\n${log}")
+  endif()
+  file(GLOB_RECURSE model_files CONFIGURE_DEPENDS "${project}/*.yaml")
+  set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS ${model_files})
+  execute_process(COMMAND ${command} get "${project}" /user_includes/include_dirs --json
+                  RESULT_VARIABLE missing OUTPUT_VARIABLE answer ERROR_QUIET)
+  set(include_dirs "")
+  if(NOT missing)
+    string(JSON count LENGTH "${answer}" data value)
+    if(count GREATER 0)
+      math(EXPR last "${count} - 1")
+      foreach(index RANGE ${last})
+        string(JSON directory GET "${answer}" data value ${index})
+        list(APPEND include_dirs "${project}/${directory}")
+      endforeach()
+    endif()
+  endif()
+  add_library(${target} INTERFACE)
+  target_include_directories(${target} INTERFACE "${output}" ${include_dirs})
+  target_link_libraries(${target} INTERFACE wireforge::runtime)
+endfunction()

wireforge-0.1.0/codegen/wireforge/__init__.py

@@ -0,0 +1,3 @@
+"""WireForge: schema-driven wire-format toolkit."""
+
+__version__ = "0.1.0"

wireforge-0.1.0/codegen/wireforge/bundle.py

@@ -0,0 +1,177 @@
+"""Bundle export and import.
+
+A bundle is one ordinary single-file project (no `include`) stamped with the current format plus
+`bundle: {content_hash, source_files}`. The sha256 covers the definition content only: stamps, the
+bundle block and key order do not change it.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import io
+import json
+from pathlib import Path
+from typing import Any, cast
+
+from ruamel.yaml import YAML
+from ruamel.yaml.error import YAMLError
+
+from wireforge import schema, vectors, versioning
+from wireforge.issues import Issue, errors_only
+from wireforge.loader import SECTIONS, load_project
+from wireforge.plain import to_plain
+from wireforge.validate import Validator, validate_project
+
+STAMP_KEYS = frozenset({"schema_version", "schema_minor", "generator", "bundle"})
+ROOT_ONLY_KEYS = ("project", "version", "description", "namespace", "defaults", "user_includes")
+# Standard layout written by import: section -> directory/file (interfaces get one file each).
+LAYOUT = {
+    "requirements": "requirements/requirements.yaml",
+    "profiles": "profiles/profiles.yaml",
+    "messages": "messages/messages.yaml",
+    "vectors": "vectors/vectors.yaml",
+}
+TYPE_SECTIONS = ("enums", "types")
+ROOT_SECTIONS = ("defines", "checksums")
+
+
+class BundleError(Exception):
+    """Export or import refused; `issues` explains why."""
+
+    def __init__(self, message: str, issues: list[Issue] | None = None) -> None:
+        """Keep the summary and the detailed issues."""
+        super().__init__(message)
+        self.issues = issues or []
+
+
+def content_hash(document: dict[str, Any]) -> str:
+    """sha256 over the definition content (stamps and key order excluded)."""
+    content = {key: value for key, value in document.items() if key not in STAMP_KEYS}
+    canonical = json.dumps(content, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+    return hashlib.sha256(canonical.encode("utf-8")).hexdigest()
+
+
+def _yaml() -> YAML:
+    yaml = YAML(typ="rt")
+    yaml.default_flow_style = False
+    yaml.width = 120
+    return yaml
+
+
+def _dump(document: dict[str, Any]) -> str:
+    stream = io.StringIO()
+    _yaml().dump(document, stream)
+    return stream.getvalue()
+
+
+def _stamped(content: dict[str, Any]) -> dict[str, Any]:
+    stamp: dict[str, object] = {}
+    versioning.stamp(stamp)
+    return {**stamp, **content}
+
+
+def build_bundle(location: Path) -> dict[str, Any]:
+    """Merge a valid project into one bundle document; raises BundleError for invalid projects."""
+    result = load_project(location)
+    issues = list(result.issues)
+    if result.project is not None:
+        issues += Validator(result.project).run()
+        if not errors_only(issues):
+            issues += vectors.check(result.project)
+    if result.project is None or errors_only(issues):
+        message = f"{location}: export refused, the project has errors"
+        raise BundleError(message, errors_only(issues))
+    root_file = Path(result.project.source.file)
+    root = cast("dict[str, Any]", to_plain(result.documents[str(root_file)]))
+    content: dict[str, Any] = {key: root[key] for key in ROOT_ONLY_KEYS if key in root}
+    for section in SECTIONS:
+        merged: dict[str, Any] = {}
+        for document in result.documents.values():
+            merged.update(cast("dict[str, Any]", to_plain(document.get(section, {}))))
+        if merged:
+            content[section] = merged
+    sources = [Path(file).relative_to(root_file.parent).as_posix() for file in result.documents]
+    bundle = _stamped(content)
+    bundle["bundle"] = {"content_hash": content_hash(content), "source_files": sources}
+    return bundle
+
+
+def export_bundle(location: Path, output: Path) -> None:
+    """Write the bundle of `location` to `output`."""
+    output.write_text(_dump(build_bundle(location)), encoding="utf-8")
+
+
+def _load_bundle(path: Path) -> dict[str, Any]:
+    try:
+        loaded = YAML(typ="safe").load(path.read_text(encoding="utf-8"))
+    except (YAMLError, OSError) as error:
+        message = f"{path}: cannot read bundle: {error}"
+        raise BundleError(message) from error
+    if not isinstance(loaded, dict):
+        message = f"{path}: a bundle must be a mapping"
+        raise BundleError(message)
+    return loaded
+
+
+def _verify(document: dict[str, Any], path: Path) -> None:
+    info = document.get("bundle")
+    expected = info.get("content_hash") if isinstance(info, dict) else None
+    if expected is None:
+        message = f"{path}: not a bundle (no bundle.content_hash); use --no-verify to import it"
+        raise BundleError(message)
+    actual = content_hash(document)
+    if actual != expected:
+        message = f"{path}: content hash mismatch (bundle says {expected}, content is {actual})"
+        raise BundleError(message)
+
+
+def _migrate(document: dict[str, Any], path: Path) -> None:
+    try:
+        versioning.migrate_document(document)
+    except (TypeError, ValueError) as error:
+        message = f"{path}: {error}"
+        raise BundleError(message) from error
+
+
+def _split(content: dict[str, Any]) -> dict[str, dict[str, Any]]:
+    """Distribute a single-file project over the standard layout (relative path -> document)."""
+    root = {key: content[key] for key in (*ROOT_ONLY_KEYS, *ROOT_SECTIONS) if key in content}
+    files: dict[str, dict[str, Any]] = {}
+    types = {section: content[section] for section in TYPE_SECTIONS if section in content}
+    if types:
+        files["types/types.yaml"] = types
+    for section, relative in LAYOUT.items():
+        if section in content:
+            files[relative] = {section: content[section]}
+    for name, interface in content.get("interfaces", {}).items():
+        files[f"interfaces/{name}.yaml"] = {"interfaces": {name: interface}}
+    directories = sorted({relative.split("/")[0] for relative in files})
+    if directories:
+        root["include"] = [f"{directory}/*.yaml" for directory in directories]
+    result = {schema.ROOT_FILE_NAME: _stamped(root)}
+    result.update({relative: _stamped(body) for relative, body in files.items()})
+    return result
+
+
+def import_bundle(
+    bundle: Path, destination: Path, *, verify: bool = True, single_file: bool = False
+) -> list[Issue]:
+    """Unpack a bundle into `destination` and return the validation issues of the result."""
+    if destination.exists() and any(destination.iterdir()):
+        message = f"{destination}: destination is not empty"
+        raise BundleError(message)
+    document = _load_bundle(bundle)
+    if verify:
+        _verify(document, bundle)
+    _migrate(document, bundle)
+    content = {key: value for key, value in document.items() if key not in STAMP_KEYS}
+    issues = schema.validate_document(_stamped(content), "project.schema.json", file=str(bundle))
+    if errors_only(issues):
+        message = f"{bundle}: the bundle is not a valid project"
+        raise BundleError(message, issues)
+    files = {schema.ROOT_FILE_NAME: _stamped(content)} if single_file else _split(content)
+    for relative, body in files.items():
+        target = destination / relative
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(_dump(body), encoding="utf-8")
+    return validate_project(destination)