dazzle-lib 0.1.0__tar.gz

dazzle_lib-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_lib-0.1.0/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: dazzle-lib
+Version: 0.1.0
+Summary: The DazzleLib bedrock: shared Protocols, TypedDict payload schemas, and exception root for the dazzle-* library stack. Stdlib-only by charter.
+Author-email: djdarcy <djdarcy@users.noreply.github.com>
+License: MIT
+Project-URL: Homepage, https://github.com/DazzleLib/dazzle-lib
+Project-URL: Repository, https://github.com/DazzleLib/dazzle-lib
+Project-URL: Issues, https://github.com/DazzleLib/dazzle-lib/issues
+Keywords: dazzlelib,protocols,typeddict,serialization,bedrock,stack
+Classifier: Development Status :: 4 - Beta
+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: Typing :: Typed
+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-lib
+
+**The DazzleLib stack's bedrock: shared Protocols, TypedDict payload schemas, and the exception root.**
+
+[![PyPI](https://img.shields.io/pypi/v/dazzle-lib)](https://pypi.org/project/dazzle-lib/)
+[![Python](https://img.shields.io/badge/python-3.9%2B-blue)](https://pypi.org/project/dazzle-lib/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Platforms](https://img.shields.io/badge/platforms-all-brightgreen)](docs/platform-support.md)
+
+Every `dazzle-*` library ([the stack](https://github.com/DazzleLib/.github/blob/main/docs/STACK-MAP.md)) builds on this package: it defines what stack objects can be expected to do (view themselves, serialize themselves) and what shapes cross-layer payloads have. **Types only** -- by charter this package contains no I/O, no path handling, no platform probing, and no behavior, forever.
+
+```bash
+pip install dazzle-lib
+```
+
+## What's inside (all of it)
+
+| Module | Contents |
+|---|---|
+| `dazzle_lib.protocols` | `Viewable` (`summary()`/`__str__`), `Serializable` (`to_dict`/`from_dict`/`to_json`, `SCHEMA_VERSION`) -- structural `Protocol`s, `runtime_checkable`, nothing is forced to subclass |
+| `dazzle_lib.payloads` | The cross-layer TypedDict schemas: `FileMetadataDict`, `TimestampsDict`, `WindowsMetadataDict`, `UnixMetadataDict`, `LinkTargetDict`, `HashResultDict` -- mirroring what `dazzle-filekit` actually produces |
+| `dazzle_lib.exceptions` | `DazzleError` root + per-domain bases (`PathIdentityError`, `FileOperationError`, `LinkError`, `PreserveError`) |
+| `dazzle_lib.mixins` | `DazzleDataMixin` -- derives `to_json`/`summary`/`__str__` from your `to_dict` |
+
+## The idea: the dict is the interface
+
+Rich objects in upper layers know how to become plain dicts; lower-layer functions take and return those dicts. The TypedDicts here are the agreed shapes, so a manifest object in `dazzle-preservelib` and a metadata collector in `dazzle-filekit` speak the same payload without sharing a class hierarchy:
+
+```python
+from dataclasses import dataclass
+from dazzle_lib import DazzleDataMixin, Serializable, FileMetadataDict
+
+@dataclass
+class TransferResult(DazzleDataMixin):
+    SCHEMA_VERSION = 1
+    path: str
+    metadata: FileMetadataDict
+
+    def to_dict(self):
+        return {"schema_version": self.SCHEMA_VERSION,
+                "path": self.path, "metadata": dict(self.metadata)}
+
+    @classmethod
+    def from_dict(cls, data):
+        return cls(path=data["path"], metadata=data["metadata"])
+
+result = TransferResult("a.txt", {"mode": 0o644, "size": 10, "timestamps": {}})
+assert isinstance(result, Serializable)   # structural -- no subclassing needed
+print(result.summary())                   # one-liner for logs
+```
+
+And one catchable root for the whole stack:
+
+```python
+from dazzle_lib import DazzleError
+try:
+    ...  # any dazzle-* library call
+except DazzleError as e:
+    ...  # caught, whichever layer raised it
+```
+
+## The charter (enforced by tests)
+
+This package is **stdlib-only forever** and contains **no behavior**. `tests/test_charter.py` fails on any banned import (`os`, `shutil`, `pathlib`, `subprocess`, ...) anywhere in the package -- a PR that needs to weaken that test is adding something that belongs in a higher layer. Admission follows the **rule of two**: a Protocol or TypedDict enters the bedrock only when two or more stack libraries need it.
+
+## The stack
+
+| Layer | Library | Role |
+|---|---|---|
+| B | **dazzle-lib** (this) | bedrock contracts |
+| L0 | [dazzle-unctools](https://github.com/DazzleLib/UNCtools) | path identity (UNC/drive/origin) |
+| L1 | [dazzle-filekit](https://github.com/DazzleLib/dazzle-filekit) | filesystem primitives |
+| L2 | dazzle-linklib *(planned)* | link serialization |
+| L3 | dazzle-preservelib *(planned)* | operation orchestration |
+| ⊥ | [dazzle-treelib](https://github.com/DazzleLib/dazzle-tree-lib) | traversal engine |
+
+Full architecture contract: [STACK-MAP.md](https://github.com/DazzleLib/.github/blob/main/docs/STACK-MAP.md). API stability policy: [docs/api-stability.md](docs/api-stability.md).
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+python -m pytest tests/ -v
+```
+
+## License
+
+MIT -- the bedrock sits beneath MIT and GPL stack members alike, so it carries the permissive license.

dazzle_lib-0.1.0/README.md

@@ -0,0 +1,88 @@
+# dazzle-lib
+
+**The DazzleLib stack's bedrock: shared Protocols, TypedDict payload schemas, and the exception root.**
+
+[![PyPI](https://img.shields.io/pypi/v/dazzle-lib)](https://pypi.org/project/dazzle-lib/)
+[![Python](https://img.shields.io/badge/python-3.9%2B-blue)](https://pypi.org/project/dazzle-lib/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Platforms](https://img.shields.io/badge/platforms-all-brightgreen)](docs/platform-support.md)
+
+Every `dazzle-*` library ([the stack](https://github.com/DazzleLib/.github/blob/main/docs/STACK-MAP.md)) builds on this package: it defines what stack objects can be expected to do (view themselves, serialize themselves) and what shapes cross-layer payloads have. **Types only** -- by charter this package contains no I/O, no path handling, no platform probing, and no behavior, forever.
+
+```bash
+pip install dazzle-lib
+```
+
+## What's inside (all of it)
+
+| Module | Contents |
+|---|---|
+| `dazzle_lib.protocols` | `Viewable` (`summary()`/`__str__`), `Serializable` (`to_dict`/`from_dict`/`to_json`, `SCHEMA_VERSION`) -- structural `Protocol`s, `runtime_checkable`, nothing is forced to subclass |
+| `dazzle_lib.payloads` | The cross-layer TypedDict schemas: `FileMetadataDict`, `TimestampsDict`, `WindowsMetadataDict`, `UnixMetadataDict`, `LinkTargetDict`, `HashResultDict` -- mirroring what `dazzle-filekit` actually produces |
+| `dazzle_lib.exceptions` | `DazzleError` root + per-domain bases (`PathIdentityError`, `FileOperationError`, `LinkError`, `PreserveError`) |
+| `dazzle_lib.mixins` | `DazzleDataMixin` -- derives `to_json`/`summary`/`__str__` from your `to_dict` |
+
+## The idea: the dict is the interface
+
+Rich objects in upper layers know how to become plain dicts; lower-layer functions take and return those dicts. The TypedDicts here are the agreed shapes, so a manifest object in `dazzle-preservelib` and a metadata collector in `dazzle-filekit` speak the same payload without sharing a class hierarchy:
+
+```python
+from dataclasses import dataclass
+from dazzle_lib import DazzleDataMixin, Serializable, FileMetadataDict
+
+@dataclass
+class TransferResult(DazzleDataMixin):
+    SCHEMA_VERSION = 1
+    path: str
+    metadata: FileMetadataDict
+
+    def to_dict(self):
+        return {"schema_version": self.SCHEMA_VERSION,
+                "path": self.path, "metadata": dict(self.metadata)}
+
+    @classmethod
+    def from_dict(cls, data):
+        return cls(path=data["path"], metadata=data["metadata"])
+
+result = TransferResult("a.txt", {"mode": 0o644, "size": 10, "timestamps": {}})
+assert isinstance(result, Serializable)   # structural -- no subclassing needed
+print(result.summary())                   # one-liner for logs
+```
+
+And one catchable root for the whole stack:
+
+```python
+from dazzle_lib import DazzleError
+try:
+    ...  # any dazzle-* library call
+except DazzleError as e:
+    ...  # caught, whichever layer raised it
+```
+
+## The charter (enforced by tests)
+
+This package is **stdlib-only forever** and contains **no behavior**. `tests/test_charter.py` fails on any banned import (`os`, `shutil`, `pathlib`, `subprocess`, ...) anywhere in the package -- a PR that needs to weaken that test is adding something that belongs in a higher layer. Admission follows the **rule of two**: a Protocol or TypedDict enters the bedrock only when two or more stack libraries need it.
+
+## The stack
+
+| Layer | Library | Role |
+|---|---|---|
+| B | **dazzle-lib** (this) | bedrock contracts |
+| L0 | [dazzle-unctools](https://github.com/DazzleLib/UNCtools) | path identity (UNC/drive/origin) |
+| L1 | [dazzle-filekit](https://github.com/DazzleLib/dazzle-filekit) | filesystem primitives |
+| L2 | dazzle-linklib *(planned)* | link serialization |
+| L3 | dazzle-preservelib *(planned)* | operation orchestration |
+| ⊥ | [dazzle-treelib](https://github.com/DazzleLib/dazzle-tree-lib) | traversal engine |
+
+Full architecture contract: [STACK-MAP.md](https://github.com/DazzleLib/.github/blob/main/docs/STACK-MAP.md). API stability policy: [docs/api-stability.md](docs/api-stability.md).
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+python -m pytest tests/ -v
+```
+
+## License
+
+MIT -- the bedrock sits beneath MIT and GPL stack members alike, so it carries the permissive license.

dazzle_lib-0.1.0/dazzle_lib/__init__.py

@@ -0,0 +1,51 @@
+"""dazzle-lib -- the DazzleLib stack's bedrock.
+
+Shared Protocols, TypedDict payload schemas, and the exception root that every
+``dazzle-*`` library builds on. Types only: this package is stdlib-only forever
+and, by charter, contains no I/O, no path handling, no platform probing, and no
+"utils". See the architecture contract:
+https://github.com/DazzleLib/.github/blob/main/docs/STACK-MAP.md
+"""
+
+from ._version import PIP_VERSION, __app_name__, __version__
+from .exceptions import (
+    DazzleError,
+    FileOperationError,
+    LinkError,
+    PathIdentityError,
+    PreserveError,
+)
+from .mixins import DazzleDataMixin
+from .payloads import (
+    FileMetadataDict,
+    HashResultDict,
+    LinkTargetDict,
+    TimestampsDict,
+    UnixMetadataDict,
+    WindowsMetadataDict,
+)
+from .protocols import Serializable, Viewable
+
+__all__ = [
+    "__version__",
+    "__app_name__",
+    "PIP_VERSION",
+    # protocols
+    "Viewable",
+    "Serializable",
+    # payload schemas
+    "TimestampsDict",
+    "WindowsMetadataDict",
+    "UnixMetadataDict",
+    "FileMetadataDict",
+    "LinkTargetDict",
+    "HashResultDict",
+    # exceptions
+    "DazzleError",
+    "PathIdentityError",
+    "FileOperationError",
+    "LinkError",
+    "PreserveError",
+    # mixin
+    "DazzleDataMixin",
+]

dazzle_lib-0.1.0/dazzle_lib/__main__.py

@@ -0,0 +1,11 @@
+"""``python -m dazzle_lib`` -- print version and charter (a library, not a tool)."""
+
+from ._version import DISPLAY_VERSION, __app_name__
+
+if __name__ == "__main__":
+    print(f"{__app_name__} {DISPLAY_VERSION}")
+    print(
+        "The DazzleLib stack's bedrock: Protocols, TypedDict payload schemas, "
+        "and the exception root.\nTypes only -- by charter this package "
+        "contains no behavior. https://github.com/DazzleLib/dazzle-lib"
+    )

dazzle_lib-0.1.0/dazzle_lib/_version.py

@@ -0,0 +1,92 @@
+"""
+Version information for dazzle-lib.
+
+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_5-20260611-b3174573"
+__app_name__ = "dazzle-lib"
+
+
+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_lib-0.1.0/dazzle_lib/exceptions.py

@@ -0,0 +1,43 @@
+"""The DazzleLib exception bedrock.
+
+One catchable root (:class:`DazzleError`) for the whole stack, plus one base
+per layer domain. Each stack library derives ITS OWN exceptions from the
+matching domain base (e.g. dazzle-preservelib's ``ManifestVersionError`` would
+subclass :class:`PreserveError`), so consumers can choose their catch
+granularity: a specific error, a domain, or the whole stack.
+
+Charter reminder: these are plain exception types. No behavior beyond
+``__init__``-style state, no I/O.
+"""
+
+__all__ = [
+    "DazzleError",
+    "PathIdentityError",
+    "FileOperationError",
+    "LinkError",
+    "PreserveError",
+]
+
+
+class DazzleError(Exception):
+    """Root of every exception raised by a DazzleLib stack library."""
+
+
+class PathIdentityError(DazzleError):
+    """Domain base for path-identity failures (dazzle-unctools, L0):
+    UNC/drive mapping, origin classification, identity probing."""
+
+
+class FileOperationError(DazzleError):
+    """Domain base for filesystem-primitive failures (dazzle-filekit, L1):
+    copy/move, metadata collect/apply, hashing, link creation."""
+
+
+class LinkError(DazzleError):
+    """Domain base for link-serialization failures (dazzle-linklib, L2):
+    .dazzlelink parsing, export/import, rebase."""
+
+
+class PreserveError(DazzleError):
+    """Domain base for orchestration failures (dazzle-preservelib, L3):
+    manifests, transactional copy/move/restore/verify, conflict policy."""

dazzle_lib-0.1.0/dazzle_lib/mixins.py

@@ -0,0 +1,42 @@
+"""The one permitted mixin: derive presentation from ``to_dict``.
+
+:class:`DazzleDataMixin` is convenience, not contract -- objects may satisfy
+the protocols without it. It exists so simple data objects don't each rewrite
+``to_json``/``__str__``/``summary`` plumbing. Anything fancier belongs in the
+object itself, not here (charter: this module stays this small).
+"""
+
+import json
+from typing import Any, Dict
+
+__all__ = ["DazzleDataMixin"]
+
+
+class DazzleDataMixin:
+    """Derives ``to_json``, ``summary`` and ``__str__`` from ``to_dict``.
+
+    The host class supplies ``to_dict()`` (and thereby decides what is
+    JSON-safe); the mixin only formats. Combined with a ``from_dict``
+    classmethod and a ``SCHEMA_VERSION`` attribute, a host class satisfies
+    both :class:`~dazzle_lib.protocols.Serializable` and
+    :class:`~dazzle_lib.protocols.Viewable`.
+    """
+
+    def to_dict(self) -> Dict[str, Any]:  # pragma: no cover - host overrides
+        raise NotImplementedError(
+            f"{type(self).__name__} must implement to_dict() to use DazzleDataMixin"
+        )
+
+    def to_json(self, *, indent: int = 2, sort_keys: bool = False) -> str:
+        """JSON form of :meth:`to_dict` (``default=str`` catches stragglers)."""
+        return json.dumps(
+            self.to_dict(), indent=indent, sort_keys=sort_keys, default=str
+        )
+
+    def summary(self) -> str:
+        """One-line description: class name plus top-level keys."""
+        keys = ", ".join(list(self.to_dict().keys())[:6])
+        return f"{type(self).__name__}({keys})"
+
+    def __str__(self) -> str:
+        return self.to_json()

dazzle_lib-0.1.0/dazzle_lib/payloads.py

@@ -0,0 +1,127 @@
+"""TypedDict payload schemas shared across the DazzleLib stack.
+
+These are THE cross-layer payload shapes (STACK-MAP D10): when one stack
+library hands file metadata, timestamps, link descriptions, or hash results to
+another, the value conforms to a shape defined here. Rich objects in upper
+layers serialize themselves INTO these shapes; primitive functions in lower
+layers take and return them directly.
+
+The shapes are not invented -- they mirror what ``dazzle-filekit`` actually
+produces today (``collect_file_metadata`` / ``collect_timestamp_info`` /
+``calculate_file_hash``), so adopting them is a typing change, not a behavior
+change. Admission policy (rule of two): a shape lives here only once two or
+more stack libraries need it.
+
+Charter reminder: this module is types-only. No I/O, no behavior.
+"""
+
+from typing import Dict, Optional, TypedDict
+
+__all__ = [
+    "TimestampsDict",
+    "WindowsMetadataDict",
+    "UnixMetadataDict",
+    "FileMetadataDict",
+    "LinkTargetDict",
+    "HashResultDict",
+]
+
+
+class TimestampsDict(TypedDict, total=False):
+    """File timestamps, epoch floats plus ISO-8601 projections.
+
+    Mirrors ``dazzle_filekit.metadata.collect_timestamp_info``. Note that
+    ``created`` carries ``st_ctime``, which is creation time on Windows but
+    inode-change time on Unix -- consumers must not assume birth-time
+    semantics cross-platform.
+    """
+
+    created: float
+    modified: float
+    accessed: float
+    created_iso: str
+    modified_iso: str
+    accessed_iso: str
+
+
+class WindowsMetadataDict(TypedDict, total=False):
+    """Windows-specific metadata (mirrors filekit's ``_collect_windows_metadata``).
+
+    With pywin32 available the rich fields are present (``attributes``,
+    owner/group + SIDs, ``security_descriptor_sddl``); without it the
+    ``attrib``-fallback path fills only the boolean flags and
+    ``attrib_output``. ``security_descriptor_sddl`` may be present-but-None
+    when the descriptor could not be stringified.
+    """
+
+    attributes: int
+    is_hidden: bool
+    is_system: bool
+    is_readonly: bool
+    is_archive: bool
+    owner: str
+    group: str
+    owner_sid: str
+    group_sid: str
+    security_descriptor_sddl: Optional[str]
+    attrib_output: str
+
+
+class UnixMetadataDict(TypedDict, total=False):
+    """Unix-specific metadata (mirrors filekit's unix branch)."""
+
+    uid: int
+    gid: int
+
+
+class _FileMetadataRequired(TypedDict):
+    mode: int
+    size: int
+    timestamps: TimestampsDict
+
+
+class FileMetadataDict(_FileMetadataRequired, total=False):
+    """A file's preservable metadata snapshot.
+
+    Mirrors ``dazzle_filekit.metadata.collect_file_metadata``: ``mode``,
+    ``size``, and ``timestamps`` are always present; exactly one of
+    ``windows`` / ``unix`` appears depending on platform; ``xattrs`` (name ->
+    base64-encoded value) appears on Unix when extended attributes exist.
+    """
+
+    windows: WindowsMetadataDict
+    unix: UnixMetadataDict
+    xattrs: Dict[str, str]
+
+
+class LinkTargetDict(TypedDict, total=False):
+    """An intrinsic description of a filesystem link, as data.
+
+    The cross-layer shape for "what is this link": produced by link analysis
+    (dazzle-filekit's ``analyze_link``), embedded in serialized link files
+    (dazzle-linklib), and consumed by orchestration policy (dazzle-preservelib).
+    Intrinsic properties only -- anything relative to a specific operation
+    (e.g. "does this link point inside the move destination") is computed at
+    the orchestration layer and does NOT belong here.
+
+    ``kind`` is one of ``"symlink"``, ``"junction"``, ``"hardlink"``.
+    ``raw_target`` is the stored target text exactly as written; ``resolved_target``
+    is its absolute resolution (when resolvable). ``target_is_directory`` is
+    best-effort (False when the target is missing).
+    """
+
+    kind: str
+    raw_target: str
+    resolved_target: str
+    is_broken: bool
+    is_circular: bool
+    target_is_directory: bool
+
+
+HashResultDict = Dict[str, str]
+"""Hash results keyed by algorithm name, hex digests as values.
+
+Mirrors ``dazzle_filekit.verification.calculate_file_hash`` (e.g.
+``{"sha256": "ab12...", "md5": "cd34..."}``). A plain ``Dict`` alias rather
+than a TypedDict because the key set is open (any hashlib algorithm).
+"""

dazzle_lib-0.1.0/dazzle_lib/protocols.py

@@ -0,0 +1,60 @@
+"""Structural protocols every DazzleLib stack object is expected to satisfy.
+
+These are :class:`typing.Protocol` definitions -- STRUCTURAL contracts, not base
+classes. Nothing in the stack is required to subclass anything here; an object
+satisfies a protocol simply by implementing its methods (and can be checked at
+runtime with ``isinstance`` because both are ``@runtime_checkable``).
+
+The design stance (STACK-MAP D10): "the dict is the interface; objects know how
+to become dicts." Rich objects in upper layers (manifest, link-data, results)
+serialize themselves INTO the plain TypedDict payload shapes defined in
+:mod:`dazzle_lib.payloads`; lower-layer functions take and return those dicts.
+
+Charter reminder: this module is types-only. No I/O, no behavior.
+"""
+
+from typing import Any, Dict, Protocol, runtime_checkable
+
+__all__ = ["Viewable", "Serializable"]
+
+
+@runtime_checkable
+class Viewable(Protocol):
+    """An object that can present itself to a human.
+
+    Expectations:
+
+    - ``summary()`` returns a SHORT one-line description suitable for list
+      views, log lines, and progress output.
+    - ``__str__`` may be longer (multi-line is fine) but must never raise.
+    """
+
+    def summary(self) -> str:
+        """One-line human-readable description of this object."""
+        ...
+
+
+@runtime_checkable
+class Serializable(Protocol):
+    """An object that can round-trip through a plain, JSON-safe dict.
+
+    Expectations:
+
+    - ``to_dict()`` returns a dict containing only JSON-safe values
+      (str/int/float/bool/None/list/dict). Where a shared payload shape
+      exists in :mod:`dazzle_lib.payloads`, the dict conforms to it.
+    - ``from_dict(data)`` is a classmethod constructing an equivalent object.
+    - ``SCHEMA_VERSION`` identifies the dict layout so readers can migrate
+      old serialized forms. Bump it on any breaking shape change.
+    """
+
+    SCHEMA_VERSION: int
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Return a JSON-safe dict representation of this object."""
+        ...
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Serializable":
+        """Construct an instance from a dict produced by :meth:`to_dict`."""
+        ...

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

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: dazzle-lib
+Version: 0.1.0
+Summary: The DazzleLib bedrock: shared Protocols, TypedDict payload schemas, and exception root for the dazzle-* library stack. Stdlib-only by charter.
+Author-email: djdarcy <djdarcy@users.noreply.github.com>
+License: MIT
+Project-URL: Homepage, https://github.com/DazzleLib/dazzle-lib
+Project-URL: Repository, https://github.com/DazzleLib/dazzle-lib
+Project-URL: Issues, https://github.com/DazzleLib/dazzle-lib/issues
+Keywords: dazzlelib,protocols,typeddict,serialization,bedrock,stack
+Classifier: Development Status :: 4 - Beta
+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: Typing :: Typed
+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-lib
+
+**The DazzleLib stack's bedrock: shared Protocols, TypedDict payload schemas, and the exception root.**
+
+[![PyPI](https://img.shields.io/pypi/v/dazzle-lib)](https://pypi.org/project/dazzle-lib/)
+[![Python](https://img.shields.io/badge/python-3.9%2B-blue)](https://pypi.org/project/dazzle-lib/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Platforms](https://img.shields.io/badge/platforms-all-brightgreen)](docs/platform-support.md)
+
+Every `dazzle-*` library ([the stack](https://github.com/DazzleLib/.github/blob/main/docs/STACK-MAP.md)) builds on this package: it defines what stack objects can be expected to do (view themselves, serialize themselves) and what shapes cross-layer payloads have. **Types only** -- by charter this package contains no I/O, no path handling, no platform probing, and no behavior, forever.
+
+```bash
+pip install dazzle-lib
+```
+
+## What's inside (all of it)
+
+| Module | Contents |
+|---|---|
+| `dazzle_lib.protocols` | `Viewable` (`summary()`/`__str__`), `Serializable` (`to_dict`/`from_dict`/`to_json`, `SCHEMA_VERSION`) -- structural `Protocol`s, `runtime_checkable`, nothing is forced to subclass |
+| `dazzle_lib.payloads` | The cross-layer TypedDict schemas: `FileMetadataDict`, `TimestampsDict`, `WindowsMetadataDict`, `UnixMetadataDict`, `LinkTargetDict`, `HashResultDict` -- mirroring what `dazzle-filekit` actually produces |
+| `dazzle_lib.exceptions` | `DazzleError` root + per-domain bases (`PathIdentityError`, `FileOperationError`, `LinkError`, `PreserveError`) |
+| `dazzle_lib.mixins` | `DazzleDataMixin` -- derives `to_json`/`summary`/`__str__` from your `to_dict` |
+
+## The idea: the dict is the interface
+
+Rich objects in upper layers know how to become plain dicts; lower-layer functions take and return those dicts. The TypedDicts here are the agreed shapes, so a manifest object in `dazzle-preservelib` and a metadata collector in `dazzle-filekit` speak the same payload without sharing a class hierarchy:
+
+```python
+from dataclasses import dataclass
+from dazzle_lib import DazzleDataMixin, Serializable, FileMetadataDict
+
+@dataclass
+class TransferResult(DazzleDataMixin):
+    SCHEMA_VERSION = 1
+    path: str
+    metadata: FileMetadataDict
+
+    def to_dict(self):
+        return {"schema_version": self.SCHEMA_VERSION,
+                "path": self.path, "metadata": dict(self.metadata)}
+
+    @classmethod
+    def from_dict(cls, data):
+        return cls(path=data["path"], metadata=data["metadata"])
+
+result = TransferResult("a.txt", {"mode": 0o644, "size": 10, "timestamps": {}})
+assert isinstance(result, Serializable)   # structural -- no subclassing needed
+print(result.summary())                   # one-liner for logs
+```
+
+And one catchable root for the whole stack:
+
+```python
+from dazzle_lib import DazzleError
+try:
+    ...  # any dazzle-* library call
+except DazzleError as e:
+    ...  # caught, whichever layer raised it
+```
+
+## The charter (enforced by tests)
+
+This package is **stdlib-only forever** and contains **no behavior**. `tests/test_charter.py` fails on any banned import (`os`, `shutil`, `pathlib`, `subprocess`, ...) anywhere in the package -- a PR that needs to weaken that test is adding something that belongs in a higher layer. Admission follows the **rule of two**: a Protocol or TypedDict enters the bedrock only when two or more stack libraries need it.
+
+## The stack
+
+| Layer | Library | Role |
+|---|---|---|
+| B | **dazzle-lib** (this) | bedrock contracts |
+| L0 | [dazzle-unctools](https://github.com/DazzleLib/UNCtools) | path identity (UNC/drive/origin) |
+| L1 | [dazzle-filekit](https://github.com/DazzleLib/dazzle-filekit) | filesystem primitives |
+| L2 | dazzle-linklib *(planned)* | link serialization |
+| L3 | dazzle-preservelib *(planned)* | operation orchestration |
+| ⊥ | [dazzle-treelib](https://github.com/DazzleLib/dazzle-tree-lib) | traversal engine |
+
+Full architecture contract: [STACK-MAP.md](https://github.com/DazzleLib/.github/blob/main/docs/STACK-MAP.md). API stability policy: [docs/api-stability.md](docs/api-stability.md).
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+python -m pytest tests/ -v
+```
+
+## License
+
+MIT -- the bedrock sits beneath MIT and GPL stack members alike, so it carries the permissive license.

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

@@ -0,0 +1,19 @@
+LICENSE
+README.md
+pyproject.toml
+dazzle_lib/__init__.py
+dazzle_lib/__main__.py
+dazzle_lib/_version.py
+dazzle_lib/exceptions.py
+dazzle_lib/mixins.py
+dazzle_lib/payloads.py
+dazzle_lib/protocols.py
+dazzle_lib.egg-info/PKG-INFO
+dazzle_lib.egg-info/SOURCES.txt
+dazzle_lib.egg-info/dependency_links.txt
+dazzle_lib.egg-info/requires.txt
+dazzle_lib.egg-info/top_level.txt
+tests/test_charter.py
+tests/test_import_stability.py
+tests/test_protocols_and_mixin.py
+tests/test_version.py

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

@@ -0,0 +1 @@
+

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

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

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

@@ -0,0 +1 @@
+dazzle_lib

dazzle_lib-0.1.0/pyproject.toml

@@ -0,0 +1,62 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "dazzle-lib"
+dynamic = ["version"]
+description = "The DazzleLib bedrock: shared Protocols, TypedDict payload schemas, and exception root for the dazzle-* library stack. Stdlib-only by charter."
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.9"
+authors = [
+    {name = "djdarcy", email = "djdarcy@users.noreply.github.com"},
+]
+keywords = ["dazzlelib", "protocols", "typeddict", "serialization", "bedrock", "stack"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "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",
+    "Typing :: Typed",
+]
+
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-cov>=4.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/DazzleLib/dazzle-lib"
+Repository = "https://github.com/DazzleLib/dazzle-lib"
+Issues = "https://github.com/DazzleLib/dazzle-lib/issues"
+
+[tool.setuptools.dynamic]
+version = {attr = "dazzle_lib._version.PIP_VERSION"}
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["dazzle_lib", "dazzle_lib.*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = "test_*.py"
+python_functions = "test_*"
+python_classes = "Test*"
+
+[tool.repokit-common]
+version-source = "dazzle_lib/_version.py"
+changelog = "CHANGELOG.md"
+repo-url = "https://github.com/DazzleLib/dazzle-lib"
+tag-prefix = "v"
+private-patterns = ["private/", "local/", ".env"]

dazzle_lib-0.1.0/setup.cfg

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

dazzle_lib-0.1.0/tests/test_charter.py

@@ -0,0 +1,96 @@
+"""The charter test: dazzle-lib is types-only, stdlib-only, behavior-free.
+
+This is the god-library guard from the STACK-MAP (D10). It fails the moment
+anyone adds I/O, path handling, platform probing, or subprocess use to the
+bedrock. A PR that needs to weaken this test is, by definition, adding
+behavior that belongs in a higher layer.
+"""
+
+import ast
+from pathlib import Path
+
+import dazzle_lib
+
+PACKAGE_DIR = Path(dazzle_lib.__file__).parent
+
+# Modules whose import (at any level) means behavior crept in.
+BANNED_IMPORTS = {
+    "os",            # I/O + platform probing
+    "io",
+    "shutil",
+    "pathlib",       # path handling is L1's domain (charter test uses it; the package may not)
+    "subprocess",
+    "socket",
+    "platform",
+    "ctypes",
+    "tempfile",
+    "glob",
+    "fnmatch",
+    "stat",
+    "sys",           # no interpreter poking either; types don't need it
+}
+
+# _version.py is generated/managed by repokit hooks and exempt (it reads nothing).
+EXEMPT_FILES = {"_version.py"}
+
+
+def _module_files():
+    return [
+        p for p in PACKAGE_DIR.glob("*.py")
+        if p.name not in EXEMPT_FILES
+    ]
+
+
+def _imports_of(path: Path):
+    tree = ast.parse(path.read_text(encoding="utf-8"))
+    found = set()
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                found.add(alias.name.split(".")[0])
+        elif isinstance(node, ast.ImportFrom):
+            if node.module and node.level == 0:
+                found.add(node.module.split(".")[0])
+    return found
+
+
+def test_no_banned_imports():
+    violations = {}
+    for path in _module_files():
+        bad = _imports_of(path) & BANNED_IMPORTS
+        if bad:
+            violations[path.name] = sorted(bad)
+    assert not violations, (
+        f"CHARTER VIOLATION -- behavior-bearing imports in the bedrock: {violations}. "
+        f"dazzle-lib is types-only; this capability belongs in a higher layer."
+    )
+
+
+def test_stdlib_only():
+    """No third-party imports, ever (the package must not even import filekit)."""
+    allowed = {"json", "typing", "enum", "dataclasses", "abc", "collections",
+               "datetime", "ast", "dazzle_lib"}
+    violations = {}
+    for path in _module_files():
+        extra = _imports_of(path) - allowed - BANNED_IMPORTS
+        if extra:
+            violations[path.name] = sorted(extra)
+    assert not violations, (
+        f"Unexpected imports in the bedrock (stdlib-only, and only the boring "
+        f"parts): {violations}. If legitimately needed, add to the allowlist "
+        f"in this test WITH a charter justification in the commit message."
+    )
+
+
+def test_no_filesystem_calls_in_source_text():
+    """Belt-and-braces: no open()/Path( usage even without an import."""
+    for path in _module_files():
+        text = path.read_text(encoding="utf-8")
+        tree = ast.parse(text)
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Call):
+                fn = node.func
+                name = getattr(fn, "id", getattr(fn, "attr", ""))
+                assert name != "open", (
+                    f"CHARTER VIOLATION -- open() call in {path.name}"
+                )

dazzle_lib-0.1.0/tests/test_import_stability.py

@@ -0,0 +1,73 @@
+"""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).
+"""
+
+import importlib
+
+LOCKED_SURFACE = {
+    "dazzle_lib": [
+        "__version__",
+        "__app_name__",
+        "Viewable",
+        "Serializable",
+        "TimestampsDict",
+        "WindowsMetadataDict",
+        "UnixMetadataDict",
+        "FileMetadataDict",
+        "LinkTargetDict",
+        "HashResultDict",
+        "DazzleError",
+        "PathIdentityError",
+        "FileOperationError",
+        "LinkError",
+        "PreserveError",
+        "DazzleDataMixin",
+    ],
+    "dazzle_lib.protocols": ["Viewable", "Serializable"],
+    "dazzle_lib.payloads": [
+        "TimestampsDict",
+        "WindowsMetadataDict",
+        "UnixMetadataDict",
+        "FileMetadataDict",
+        "LinkTargetDict",
+        "HashResultDict",
+    ],
+    "dazzle_lib.exceptions": [
+        "DazzleError",
+        "PathIdentityError",
+        "FileOperationError",
+        "LinkError",
+        "PreserveError",
+    ],
+    "dazzle_lib.mixins": ["DazzleDataMixin"],
+}
+
+
+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_exception_hierarchy_rooted():
+    from dazzle_lib import (
+        DazzleError,
+        FileOperationError,
+        LinkError,
+        PathIdentityError,
+        PreserveError,
+    )
+    for exc in (PathIdentityError, FileOperationError, LinkError, PreserveError):
+        assert issubclass(exc, DazzleError)
+    assert issubclass(DazzleError, Exception)

dazzle_lib-0.1.0/tests/test_protocols_and_mixin.py

@@ -0,0 +1,84 @@
+"""Protocol satisfaction + mixin behavior: a plain dataclass with to_dict/
+from_dict/SCHEMA_VERSION satisfies Serializable WITHOUT subclassing anything --
+the structural-typing promise the bedrock makes."""
+
+import json
+from dataclasses import dataclass
+from typing import Any, Dict
+
+from dazzle_lib import DazzleDataMixin, Serializable, Viewable
+
+
+@dataclass
+class SampleResult(DazzleDataMixin):
+    SCHEMA_VERSION = 1
+    name: str = "demo"
+    count: int = 3
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {"schema_version": self.SCHEMA_VERSION, "name": self.name,
+                "count": self.count}
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "SampleResult":
+        return cls(name=data["name"], count=data["count"])
+
+
+class BareDuck:
+    """No mixin, no inheritance -- pure structural satisfaction."""
+
+    SCHEMA_VERSION = 2
+
+    def to_dict(self):
+        return {"x": 1}
+
+    @classmethod
+    def from_dict(cls, data):
+        return cls()
+
+    def summary(self):
+        return "a bare duck"
+
+
+def test_dataclass_with_mixin_satisfies_serializable():
+    s = SampleResult()
+    assert isinstance(s, Serializable)
+    assert isinstance(s, Viewable)
+
+
+def test_bare_class_satisfies_protocols_structurally():
+    d = BareDuck()
+    assert isinstance(d, Serializable)
+    assert isinstance(d, Viewable)
+
+
+def test_non_conforming_object_rejected():
+    assert not isinstance(object(), Serializable)
+    assert not isinstance(object(), Viewable)
+
+
+def test_round_trip():
+    s = SampleResult(name="rt", count=7)
+    again = SampleResult.from_dict(s.to_dict())
+    assert again == s
+
+
+def test_mixin_to_json_and_str():
+    s = SampleResult(name="js", count=1)
+    parsed = json.loads(s.to_json())
+    assert parsed == {"schema_version": 1, "name": "js", "count": 1}
+    assert json.loads(str(s)) == parsed
+
+
+def test_mixin_summary_is_one_line():
+    s = SampleResult()
+    assert "\n" not in s.summary()
+    assert "SampleResult" in s.summary()
+
+
+def test_payload_typeddicts_are_constructible():
+    from dazzle_lib import FileMetadataDict, TimestampsDict
+
+    ts: TimestampsDict = {"modified": 1.0, "accessed": 2.0, "created": 3.0}
+    md: FileMetadataDict = {"mode": 0o644, "size": 10, "timestamps": ts}
+    assert md["timestamps"]["modified"] == 1.0

dazzle_lib-0.1.0/tests/test_version.py

@@ -0,0 +1,50 @@
+"""Tests for version module."""
+
+from dazzle_lib._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-lib"
+
+
+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)