Content-addressable link-record library -- the L2 serialization layer of the DazzleLib stack.
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
.dazzlelinkfile 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).
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.)
| Layer | Library | Role |
|---|---|---|
| B | dazzle-lib | bedrock contracts (Protocols, TypedDicts, exception root) |
| L0 | dazzle-unctools | path identity (UNC/drive/origin) |
| L1 | dazzle-filekit | filesystem primitives |
| L2 | dazzle-linklib (this) | link record + resolver |
| L3 | dazzle-preservelib (planned) | operation orchestration |
| ⊥ | dazzle-treelib | traversal engine |
Full architecture contract: STACK-MAP.md. API stability policy: docs/api-stability.md.
Pre-alpha (0.2.0) -- first functional release. The link-record core (stack
phase P2) is extracted from the dazzlelink tool: the record model
(DazzleLinkData), record discovery/rebase (find_dazzlelinks/scan/rebase),
and the injectable target resolver (resolve_target). It is verified
wire-compatible with the published dazzlelink 0.8.0 tool in both directions.
The down-stack delegation of filesystem mechanics to dazzle-filekit (L1) and
unctools (L0) follows -- see the
Roadmap.
from dazzle_linklib import DazzleLinkData, find_dazzlelinks, resolve_target
# Read a .dazzlelink record (nested JSON, legacy flat, or embedded-script form).
record = DazzleLinkData.from_file("photo.png.dazzlelink")
print(record.get_target_path())
# Author a record with typed locators + a content identity (Relinker-ready).
record = DazzleLinkData()
record.set_target_path(r"D:\archive\photo.png")
record.add_locator("ipfs", "QmHash...")
record.set_content_id("sha256", "deadbeef...")
record.save_to_file("photo.png.dazzlelink")
# Discover records under a tree and resolve one to its first live locator.
for path in find_dazzlelinks("backup/", recursive=True):
located = resolve_target(DazzleLinkData.from_file(str(path)))
print(path, "->", located)pip install dazzle-linklibgit clone https://github.com/DazzleLib/dazzle-linklib.git
cd dazzle-linklib
pip install -e ".[dev]"Contributions welcome! Please open an issue or submit a pull request.
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.shTwo house rules this library lives by:
- Dependencies point down only. L2 consumes the bedrock and the layers below
it; it never imports its consumers (the
dazzlelinkCLI or preserve). Thetests/test_no_upstream_imports.pycanary enforces this. - The public surface is locked. Record/discovery/resolver symbols are pinned
by
tests/test_import_stability.py; changes follow docs/api-stability.md (locked surface, noisy-shim deprecation, additive-only schema evolution).
Like the project?
This project is licensed under the MIT License -- see the LICENSE file for details. The whole DazzleLib stack is MIT (STACK-MAP D11).