dazzle-linklib 0.1.0__tar.gz

dazzle_linklib-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dustin Darcy
+
+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.

dazzle_linklib-0.1.0/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: dazzle-linklib
+Version: 0.1.0
+Summary: Content-addressable link-record library -- the DazzleLib stack's L2 serialization layer (typed locators, content_id, export/import/rebase/scan).
+Author-email: djdarcy <djdarcy@users.noreply.github.com>
+License: MIT
+Project-URL: Homepage, https://github.com/DazzleLib/dazzle-linklib
+Project-URL: Repository, https://github.com/DazzleLib/dazzle-linklib
+Project-URL: Issues, https://github.com/DazzleLib/dazzle-linklib/issues
+Keywords: dazzlelib,links,symlink,junction,serialization,content-addressable,anti-link-rot,relinker,stack
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Filesystems
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Dynamic: license-file
+
+# dazzle-linklib
+
+[![PyPI](https://img.shields.io/pypi/v/dazzle-linklib?color=green)](https://pypi.org/project/dazzle-linklib/)
+[![Release Date](https://img.shields.io/github/release-date/DazzleLib/dazzle-linklib?color=green)](https://github.com/DazzleLib/dazzle-linklib/releases)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS%20%7C%20BSD-lightgrey.svg)](docs/platform-support.md)
+
+**Content-addressable link-record library** -- the **L2** serialization layer of
+the [DazzleLib stack](https://github.com/DazzleLib/.github/blob/main/docs/STACK-MAP.md).
+
+A link record maps an **identity** to a **typed list of locators** plus
+metadata, and knows how to serialize, find, and resolve itself. One model
+serves three consumers:
+
+- the **dazzlelink** filesystem CLI (the `.dazzlelink` file format),
+- **preserve**'s content-hash manifest (L3), and
+- **Relinker** -- a hash-addressed, decentralized anti-link-rot resolver
+  (`rln.kr/{hash}` -> a multi-protocol location set).
+
+## What this owns (and what it doesn't)
+
+`dazzle-linklib` owns the link **record**: its schema, JSON I/O, the locator
+list, `content_id`, relation edges, and the injectable target resolver. It
+**delegates** the rest down the stack:
+
+| Concern | Layer |
+|---|---|
+| Link record, locators, `content_id`, relations, resolve | **dazzle-linklib (L2, this lib)** |
+| File/link mechanics (create/detect/read, copy, hash, metadata) | `dazzle-filekit` (L1) |
+| UNC <-> drive identity, path origin classification | `unctools` (L0) |
+| Shared Protocols / TypedDicts / exception root | `dazzle-lib` (B) |
+| Graph **traversal** (walking the records' relation edges) | `dazzletreelib` (perpendicular) |
+
+"Records that point at each other" live here; "walking and interpreting those
+pointers" do not. (See the L2 design rationale, decision D6.)
+
+## Status
+
+**0.1.0 is a name-reservation placeholder (pre-alpha).** It is published to
+PyPI to claim the name, but exposes only its version -- there is no functional
+content yet. The extraction of `DazzleLinkData` and the resolver from the
+`dazzlelink` tool is stack phase **P2** and lands in a later release -- see the
+[Roadmap](https://github.com/DazzleLib/dazzle-linklib/issues/2).
+
+## Installation
+
+```bash
+pip install dazzle-linklib
+```
+
+### From source
+
+```bash
+git clone https://github.com/DazzleLib/dazzle-linklib.git
+cd dazzle-linklib
+pip install -e ".[dev]"
+```
+
+## Development
+
+```bash
+python -m venv .venv
+source .venv/bin/activate   # or .venv\Scripts\activate on Windows
+pip install -e ".[dev]"
+
+# Run tests
+python -m pytest tests/ -v
+
+# Install git hooks
+bash scripts/install-hooks.sh
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE) for details.

dazzle_linklib-0.1.0/README.md

@@ -0,0 +1,76 @@
+# dazzle-linklib
+
+[![PyPI](https://img.shields.io/pypi/v/dazzle-linklib?color=green)](https://pypi.org/project/dazzle-linklib/)
+[![Release Date](https://img.shields.io/github/release-date/DazzleLib/dazzle-linklib?color=green)](https://github.com/DazzleLib/dazzle-linklib/releases)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS%20%7C%20BSD-lightgrey.svg)](docs/platform-support.md)
+
+**Content-addressable link-record library** -- the **L2** serialization layer of
+the [DazzleLib stack](https://github.com/DazzleLib/.github/blob/main/docs/STACK-MAP.md).
+
+A link record maps an **identity** to a **typed list of locators** plus
+metadata, and knows how to serialize, find, and resolve itself. One model
+serves three consumers:
+
+- the **dazzlelink** filesystem CLI (the `.dazzlelink` file format),
+- **preserve**'s content-hash manifest (L3), and
+- **Relinker** -- a hash-addressed, decentralized anti-link-rot resolver
+  (`rln.kr/{hash}` -> a multi-protocol location set).
+
+## What this owns (and what it doesn't)
+
+`dazzle-linklib` owns the link **record**: its schema, JSON I/O, the locator
+list, `content_id`, relation edges, and the injectable target resolver. It
+**delegates** the rest down the stack:
+
+| Concern | Layer |
+|---|---|
+| Link record, locators, `content_id`, relations, resolve | **dazzle-linklib (L2, this lib)** |
+| File/link mechanics (create/detect/read, copy, hash, metadata) | `dazzle-filekit` (L1) |
+| UNC <-> drive identity, path origin classification | `unctools` (L0) |
+| Shared Protocols / TypedDicts / exception root | `dazzle-lib` (B) |
+| Graph **traversal** (walking the records' relation edges) | `dazzletreelib` (perpendicular) |
+
+"Records that point at each other" live here; "walking and interpreting those
+pointers" do not. (See the L2 design rationale, decision D6.)
+
+## Status
+
+**0.1.0 is a name-reservation placeholder (pre-alpha).** It is published to
+PyPI to claim the name, but exposes only its version -- there is no functional
+content yet. The extraction of `DazzleLinkData` and the resolver from the
+`dazzlelink` tool is stack phase **P2** and lands in a later release -- see the
+[Roadmap](https://github.com/DazzleLib/dazzle-linklib/issues/2).
+
+## Installation
+
+```bash
+pip install dazzle-linklib
+```
+
+### From source
+
+```bash
+git clone https://github.com/DazzleLib/dazzle-linklib.git
+cd dazzle-linklib
+pip install -e ".[dev]"
+```
+
+## Development
+
+```bash
+python -m venv .venv
+source .venv/bin/activate   # or .venv\Scripts\activate on Windows
+pip install -e ".[dev]"
+
+# Run tests
+python -m pytest tests/ -v
+
+# Install git hooks
+bash scripts/install-hooks.sh
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE) for details.

dazzle_linklib-0.1.0/dazzle_linklib/__init__.py

@@ -0,0 +1,30 @@
+"""dazzle-linklib -- the DazzleLib stack's L2 link-record library.
+
+A **content-addressable link record**: one model that maps an identity to a
+typed list of locators plus metadata, and knows how to serialize, find, and
+resolve itself. It is the portable-DATA layer beneath three consumers:
+
+* the **dazzlelink** filesystem CLI (the `.dazzlelink` file format),
+* **preserve**'s content-hash manifest (L3), and
+* **Relinker** -- a hash-addressed, decentralized anti-link-rot resolver
+  (``rln.kr/{hash}`` -> a multi-protocol location set).
+
+The boundary (STACK-MAP, layers B/L0/L1/L2/L3): this library owns the link
+RECORD -- its schema, JSON I/O, locator list, ``content_id``, and relation
+edges -- and the injectable target resolver. It does NOT own filesystem
+mechanics (those delegate down to ``dazzle-filekit`` L1), UNC/drive identity
+(``unctools`` L0), or graph TRAVERSAL (``dazzletreelib`` is the perpendicular
+traversal tier). "Records that point at each other" live here; "walking and
+interpreting those pointers" do not (see the L2 design DWP, decision D6).
+
+Status: **scaffold (0.1.0, pre-alpha).** The extraction of ``DazzleLinkData``
+and the resolver from the dazzlelink tool is stack phase **P2** -- tracked on
+the roadmap (issue #2). Until then this package exposes only its version.
+
+License: MIT (whole stack; STACK-MAP D11). Architecture contract:
+https://github.com/DazzleLib/.github/blob/main/docs/STACK-MAP.md
+"""
+
+from ._version import PIP_VERSION, __app_name__, __version__
+
+__all__ = ["__version__", "__app_name__", "PIP_VERSION"]

dazzle_linklib-0.1.0/dazzle_linklib/__main__.py

@@ -0,0 +1,16 @@
+"""Allow running as: python -m dazzle_linklib
+
+dazzle-linklib is a LIBRARY, not a CLI -- the `dazzlelink` command lives in the
+DazzleTools/dazzlelink tool (STACK-MAP D1). Running the module just reports the
+installed version.
+"""
+from . import __app_name__, __version__
+
+
+def main() -> None:
+    print(f"{__app_name__} {__version__}")
+    print("Library only -- the dazzlelink CLI lives in DazzleTools/dazzlelink.")
+
+
+if __name__ == "__main__":
+    main()

dazzle_linklib-0.1.0/dazzle_linklib/_version.py

@@ -0,0 +1,92 @@
+"""
+Version information for dazzle-linklib.
+
+This file is the canonical source for version numbers.
+The __version__ string is automatically updated by git hooks
+with build metadata (branch, build number, date, commit hash).
+
+Format: MAJOR.MINOR.PATCH[-PHASE]_BRANCH_BUILD-YYYYMMDD-COMMITHASH
+Example: 0.1.0_main_1-20260101-a1b2c3d4
+
+Version levels:
+  PROJECT_PHASE: Global project maturity (prealpha -> alpha -> beta -> stable).
+       Changes rarely, when the overall project hits a threshold.
+  PHASE:         Per-MINOR feature set maturity (alpha -> beta -> "" for stable).
+       Drops when a MINOR's feature set is complete.
+"""
+
+# Version components - edit these for version bumps
+MAJOR = 0
+MINOR = 1
+PATCH = 0
+PHASE = ""  # Per-MINOR feature set: "" (stable), "alpha", "beta", "rc1", etc.
+
+# Project-level phase (independent of version phase)
+PROJECT_PHASE = ""  # "prealpha", "alpha", "beta", "stable", or ""
+
+# Auto-updated by git hooks - do not edit manually
+__version__ = "0.1.0_main_7-20260619-08de0656"
+__app_name__ = "dazzle-linklib"
+
+
+def get_version():
+    """Return the full version string including branch and build info."""
+    return __version__
+
+
+def get_base_version():
+    """Return the semantic version string (MAJOR.MINOR.PATCH[-PHASE])."""
+    if "_" in __version__:
+        return __version__.split("_")[0]
+    base = f"{MAJOR}.{MINOR}.{PATCH}"
+    if PHASE:
+        base = f"{base}-{PHASE}"
+    return base
+
+
+def get_display_version():
+    """Return a human-friendly version string with project phase.
+
+    Example: 'PREALPHA 0.1.0-alpha' or 'BETA 0.5.1' or '1.0.0'
+    """
+    base = get_base_version()
+    if PROJECT_PHASE and PROJECT_PHASE != "stable":
+        return f"{PROJECT_PHASE.upper()} {base}"
+    return base
+
+
+def get_pip_version():
+    """
+    Return PEP 440 compliant version for pip/setuptools.
+
+    Converts our version format to PEP 440:
+    - Main branch: 0.1.0_main_3-20260404-hash -> 0.1.0
+    - Dev branch: 0.1.0_dev_3-20260404-hash -> 0.1.0.dev3
+    - Alpha: 0.1.0-alpha_main_3 -> 0.1.0a0
+    """
+    base = f"{MAJOR}.{MINOR}.{PATCH}"
+
+    # Map phase to PEP 440 pre-release segment
+    phase_map = {"alpha": "a0", "beta": "b0"}
+    if PHASE:
+        base += phase_map.get(PHASE, PHASE)
+
+    if "_" not in __version__:
+        return base
+
+    parts = __version__.split("_")
+    branch = parts[1] if len(parts) > 1 else "unknown"
+
+    if branch == "main":
+        return base
+    else:
+        build_info = "_".join(parts[2:]) if len(parts) > 2 else ""
+        build_num = build_info.split("-")[0] if "-" in build_info else "0"
+        return f"{base}.dev{build_num}"
+
+
+# For convenience in imports
+VERSION = get_version()
+BASE_VERSION = get_base_version()
+PIP_VERSION = get_pip_version()
+DISPLAY_VERSION = get_display_version()

dazzle_linklib-0.1.0/dazzle_linklib.egg-info/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: dazzle-linklib
+Version: 0.1.0
+Summary: Content-addressable link-record library -- the DazzleLib stack's L2 serialization layer (typed locators, content_id, export/import/rebase/scan).
+Author-email: djdarcy <djdarcy@users.noreply.github.com>
+License: MIT
+Project-URL: Homepage, https://github.com/DazzleLib/dazzle-linklib
+Project-URL: Repository, https://github.com/DazzleLib/dazzle-linklib
+Project-URL: Issues, https://github.com/DazzleLib/dazzle-linklib/issues
+Keywords: dazzlelib,links,symlink,junction,serialization,content-addressable,anti-link-rot,relinker,stack
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Filesystems
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Dynamic: license-file
+
+# dazzle-linklib
+
+[![PyPI](https://img.shields.io/pypi/v/dazzle-linklib?color=green)](https://pypi.org/project/dazzle-linklib/)
+[![Release Date](https://img.shields.io/github/release-date/DazzleLib/dazzle-linklib?color=green)](https://github.com/DazzleLib/dazzle-linklib/releases)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS%20%7C%20BSD-lightgrey.svg)](docs/platform-support.md)
+
+**Content-addressable link-record library** -- the **L2** serialization layer of
+the [DazzleLib stack](https://github.com/DazzleLib/.github/blob/main/docs/STACK-MAP.md).
+
+A link record maps an **identity** to a **typed list of locators** plus
+metadata, and knows how to serialize, find, and resolve itself. One model
+serves three consumers:
+
+- the **dazzlelink** filesystem CLI (the `.dazzlelink` file format),
+- **preserve**'s content-hash manifest (L3), and
+- **Relinker** -- a hash-addressed, decentralized anti-link-rot resolver
+  (`rln.kr/{hash}` -> a multi-protocol location set).
+
+## What this owns (and what it doesn't)
+
+`dazzle-linklib` owns the link **record**: its schema, JSON I/O, the locator
+list, `content_id`, relation edges, and the injectable target resolver. It
+**delegates** the rest down the stack:
+
+| Concern | Layer |
+|---|---|
+| Link record, locators, `content_id`, relations, resolve | **dazzle-linklib (L2, this lib)** |
+| File/link mechanics (create/detect/read, copy, hash, metadata) | `dazzle-filekit` (L1) |
+| UNC <-> drive identity, path origin classification | `unctools` (L0) |
+| Shared Protocols / TypedDicts / exception root | `dazzle-lib` (B) |
+| Graph **traversal** (walking the records' relation edges) | `dazzletreelib` (perpendicular) |
+
+"Records that point at each other" live here; "walking and interpreting those
+pointers" do not. (See the L2 design rationale, decision D6.)
+
+## Status
+
+**0.1.0 is a name-reservation placeholder (pre-alpha).** It is published to
+PyPI to claim the name, but exposes only its version -- there is no functional
+content yet. The extraction of `DazzleLinkData` and the resolver from the
+`dazzlelink` tool is stack phase **P2** and lands in a later release -- see the
+[Roadmap](https://github.com/DazzleLib/dazzle-linklib/issues/2).
+
+## Installation
+
+```bash
+pip install dazzle-linklib
+```
+
+### From source
+
+```bash
+git clone https://github.com/DazzleLib/dazzle-linklib.git
+cd dazzle-linklib
+pip install -e ".[dev]"
+```
+
+## Development
+
+```bash
+python -m venv .venv
+source .venv/bin/activate   # or .venv\Scripts\activate on Windows
+pip install -e ".[dev]"
+
+# Run tests
+python -m pytest tests/ -v
+
+# Install git hooks
+bash scripts/install-hooks.sh
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE) for details.

dazzle_linklib-0.1.0/dazzle_linklib.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+dazzle_linklib/__init__.py
+dazzle_linklib/__main__.py
+dazzle_linklib/_version.py
+dazzle_linklib.egg-info/PKG-INFO
+dazzle_linklib.egg-info/SOURCES.txt
+dazzle_linklib.egg-info/dependency_links.txt
+dazzle_linklib.egg-info/requires.txt
+dazzle_linklib.egg-info/top_level.txt
+tests/test_import_stability.py
+tests/test_version.py

dazzle_linklib-0.1.0/dazzle_linklib.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

dazzle_linklib-0.1.0/dazzle_linklib.egg-info/requires.txt

@@ -0,0 +1,4 @@
+
+[dev]
+pytest>=7.0.0
+pytest-cov>=4.0.0

dazzle_linklib-0.1.0/dazzle_linklib.egg-info/top_level.txt

@@ -0,0 +1 @@
+dazzle_linklib

dazzle_linklib-0.1.0/pyproject.toml

@@ -0,0 +1,65 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "dazzle-linklib"
+dynamic = ["version"]
+description = "Content-addressable link-record library -- the DazzleLib stack's L2 serialization layer (typed locators, content_id, export/import/rebase/scan)."
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.9"
+authors = [
+    {name = "djdarcy", email = "djdarcy@users.noreply.github.com"},
+]
+keywords = ["dazzlelib", "links", "symlink", "junction", "serialization", "content-addressable", "anti-link-rot", "relinker", "stack"]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: System :: Filesystems",
+]
+
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-cov>=4.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/DazzleLib/dazzle-linklib"
+Repository = "https://github.com/DazzleLib/dazzle-linklib"
+Issues = "https://github.com/DazzleLib/dazzle-linklib/issues"
+
+# Library-only: no console_scripts. The `dazzlelink` CLI lives in the
+# DazzleTools/dazzlelink tool, which consumes this library (STACK-MAP D1).
+
+[tool.setuptools.dynamic]
+version = {attr = "dazzle_linklib._version.PIP_VERSION"}
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["dazzle_linklib", "dazzle_linklib.*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = "test_*.py"
+python_functions = "test_*"
+python_classes = "Test*"
+
+[tool.repokit-common]
+version-source = "dazzle_linklib/_version.py"
+changelog = "CHANGELOG.md"
+repo-url = "https://github.com/DazzleLib/dazzle-linklib"
+tag-prefix = "v"
+private-patterns = ["private/", "local/", ".env"]

dazzle_linklib-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

dazzle_linklib-0.1.0/tests/test_import_stability.py

@@ -0,0 +1,41 @@
+"""Import-stability canary (see docs/api-stability.md).
+
+Every symbol listed here is part of the locked public API. If this test
+fails, a consumer somewhere breaks: do NOT silently fix the test -- follow
+the api-stability.md process (deprecate with a noisy shim, register it,
+slate removal).
+
+The locked surface is intentionally tiny at the 0.1.0 scaffold stage (version
+exports only). The record model (DazzleLinkData, export/import/scan/rebase,
+resolve_target) joins this canary at its P2 release.
+"""
+
+import importlib
+
+LOCKED_SURFACE = {
+    "dazzle_linklib": [
+        "__version__",
+        "__app_name__",
+        "PIP_VERSION",
+    ],
+}
+
+
+def test_locked_surface_importable():
+    missing = []
+    for module_name, symbols in LOCKED_SURFACE.items():
+        module = importlib.import_module(module_name)
+        for symbol in symbols:
+            if not hasattr(module, symbol):
+                missing.append(f"{module_name}.{symbol}")
+    assert not missing, (
+        f"Locked API symbols missing: {missing} -- see docs/api-stability.md "
+        f"before changing the public surface."
+    )
+
+
+def test_package_is_importable():
+    """The package imports cleanly with no side effects at import time."""
+    mod = importlib.import_module("dazzle_linklib")
+    assert isinstance(mod.__version__, str)
+    assert mod.__app_name__ == "dazzle-linklib"

dazzle_linklib-0.1.0/tests/test_version.py

@@ -0,0 +1,50 @@
+"""Tests for version module."""
+
+from dazzle_linklib._version import (
+    MAJOR, MINOR, PATCH, PHASE, PROJECT_PHASE,
+    get_version, get_base_version, get_display_version, get_pip_version,
+    __app_name__,
+)
+
+
+def test_app_name():
+    assert __app_name__ == "dazzle-linklib"
+
+
+def test_version_components():
+    assert isinstance(MAJOR, int)
+    assert isinstance(MINOR, int)
+    assert isinstance(PATCH, int)
+
+
+def test_phase_valid():
+    """PHASE is empty string (stable release) or a string like 'alpha', 'beta', 'rc1'."""
+    assert isinstance(PHASE, str)
+
+
+def test_get_version_returns_string():
+    v = get_version()
+    assert isinstance(v, str)
+    assert len(v) > 0
+
+
+def test_base_version_format():
+    base = get_base_version()
+    assert base.startswith(f"{MAJOR}.{MINOR}.{PATCH}")
+
+
+def test_display_version_includes_project_phase():
+    display = get_display_version()
+    if PROJECT_PHASE and PROJECT_PHASE != "stable":
+        assert PROJECT_PHASE.upper() in display
+    else:
+        assert display == get_base_version()
+
+
+def test_pip_version_pep440():
+    pip_v = get_pip_version()
+    assert "-" not in pip_v
+    if PHASE:
+        assert any(c.isalpha() for c in pip_v.split(".")[-1])
+    else:
+        assert all(c.isdigit() or c == "." for c in pip_v)