tiergraph 0.1.0__tar.gz

tiergraph-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,87 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  test-python-313:
+    name: test (Python 3.13)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      # Only run the 3.13 compatibility suite when code changes; a docs- or
+      # metadata-only change cannot affect it, and the job still reports success
+      # so a required check does not hang.
+      - uses: dorny/paths-filter@v3
+        id: changes
+        with:
+          filters: |
+            code:
+              - 'src/**'
+              - 'tests/**'
+              - 'examples/**'
+              - 'scripts/**'
+              - 'pyproject.toml'
+              - '.github/workflows/ci.yml'
+      - if: steps.changes.outputs.code == 'true'
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      - if: steps.changes.outputs.code == 'true'
+        run: python -m pip install --upgrade pip
+      - if: steps.changes.outputs.code == 'true'
+        run: python -m pip install -e ".[test]"
+      # The documentation gate type-checks doc code fences with mypy (a dev-tooling
+      # concern pinned to the 3.12 environment) and is covered by the full make check job.
+      - if: steps.changes.outputs.code == 'true'
+        run: python -m pytest --deselect tests/test_docs.py::test_documentation_gate_is_current
+      - if: steps.changes.outputs.code != 'true'
+        run: echo "No code changed; skipping the 3.13 compatibility suite."
+
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      # The full gate runs whenever code or gate-checked docs change. A change
+      # confined to inert files -- the release workflow, release notes, the
+      # license -- skips it, and the job still reports success so the required
+      # check does not hang. Anything under src, tests, docs, examples, scripts,
+      # or the build files keeps docs currency and code gated.
+      - uses: dorny/paths-filter@v3
+        id: changes
+        with:
+          filters: |
+            gated:
+              - 'src/**'
+              - 'tests/**'
+              - 'examples/**'
+              - 'scripts/**'
+              - 'docs/**'
+              - 'pyproject.toml'
+              - 'Makefile'
+              - 'README.md'
+              - '.github/workflows/ci.yml'
+      - if: steps.changes.outputs.gated == 'true'
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      # make check builds its own environment, so CI runs the same path as a
+      # developer rather than a parallel one that can drift.
+      - if: steps.changes.outputs.gated == 'true'
+        run: make check
+      - if: steps.changes.outputs.gated != 'true'
+        run: echo "Only inert files changed (workflow or release notes); skipping the full gate."

tiergraph-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,55 @@
+name: Publish
+
+# Build once, then publish via PyPI Trusted Publishing (OIDC) -- no API tokens.
+# Cut a GitHub Release (tag vX.Y.Z) to publish to PyPI.
+#
+# One-time setup (see RELEASING.md):
+#   - PyPI:   add a Trusted Publisher (project tiergraph, this repo, workflow
+#             publish.yml, environment "pypi").
+#   - GitHub: create environment "pypi" (Settings > Environments).
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: build sdist + wheel
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - run: python -m pip install --upgrade pip build
+      - run: python -m build
+      - name: Verify version matches release tag
+        env:
+          TAG: ${{ github.event.release.tag_name }}
+        run: |
+          VERSION=$(PYTHONPATH=src python -c "import tiergraph; print(tiergraph.__version__)")
+          echo "tiergraph.__version__=$VERSION release tag=$TAG"
+          test "$VERSION" = "${TAG#v}"
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-pypi:
+    name: publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/tiergraph
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

tiergraph-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+untracked/
+
+__pycache__/
+*.py[cod]
+.coverage
+.hypothesis/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+build/
+dist/
+*.egg-info/
+.venv/

tiergraph-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,32 @@
+minimum_pre_commit_version: "3.0.0"
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-merge-conflict
+      - id: check-added-large-files
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.16.1
+    hooks:
+      - id: ruff-check
+        args: ["--fix"]
+      - id: ruff-format
+
+  - repo: local
+    hooks:
+      - id: tracked-clean
+        name: tracked files carry nothing local
+        entry: python scripts/check_tracked_clean.py
+        language: system
+        pass_filenames: false
+      - id: documented
+        name: public names carry a docstring
+        entry: python scripts/check_documented.py
+        language: system
+        pass_filenames: false

tiergraph-0.1.0/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-08-23
+
+### Added
+
+- Immutable ordered-tier graphs with declared namespaces, typed attributes, item and boundary references, and simple, bipartite, and polyadic relations.
+- A checked opcode `Program` and build machine for declaring and populating graphs, with bounded repetition, execution traces, and unrolling to an immutable `Graph`.
+- Semiring folds over finite dependency DAGs, including exact min- and max-plus carriers and the `PATH` semiring's tied best-path provenance and capped n-best ranked witnesses.
+- Clock profiles for structural refinement and physical timing, including `ClockProfile.from_position_values`, optional shared-boundary collapse, and the `is_structural` capability flag.
+- Deterministic span projections through `tiergraph.spanview`, with text, JSON, JSON Lines, and HTML emitters, plus `tiergraph_dot.dumps_spans` visualization.
+- Deterministic Graphviz DOT rendering through `tiergraph_dot.dumps`, including `DotPresentation` hooks and structural-clock occupied-spine placement and relation rendering.
+- TG-PATH canonical addressing for structural and durable items and boundaries, profile-owned alternatives, kind checks, and typed refusals with offender details.
+- Canonical selection, bounded bipartite walks, ordered polyadic traversal, and ordered containment queries that preserve declared incidence and child order where applicable.
+
+[0.1.0]: https://github.com/lenzo-ka/tiergraph/releases/tag/v0.1.0

tiergraph-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,75 @@
+# Contributing to tiergraph
+
+Thank you for contributing to tiergraph. This project is alpha software, so a
+small, well-tested change is especially valuable.
+
+## Set up a development environment
+
+tiergraph requires Python 3.12 or later. Development is pinned to Python 3.12,
+the supported floor, so newer Python features do not enter the codebase
+accidentally. From the repository root, create the isolated development
+environment and install the project with its development dependencies:
+
+```console
+make venv
+```
+
+By default, this uses `python3.12` and creates `.venv`. You can override the
+interpreter with `PYTHON=/path/to/python3.12` or the environment directory with
+`VENV=/path/to/venv`.
+
+## Check a change
+
+Run the same full gate used by CI:
+
+```console
+make check
+```
+
+The gate runs Ruff linting and formatting checks, strict mypy checks, pytest,
+the test suite in separate processes with hash seeds 0, 12345, and 999, JSON
+Schema currency checks, documentation currency checks, the tracked-file hygiene
+check, and the public-docstring check. Coverage is measured only for the shipped
+`tiergraph` and `tiergraph_dot` packages and must remain at 100% branch coverage.
+
+The repository also provides a pre-commit configuration. After installing
+`pre-commit` separately, enable it in your checkout with:
+
+```console
+pre-commit install
+pre-commit run --all-files
+```
+
+Those hooks apply basic file checks and Ruff, then run the tracked-file hygiene
+and public-docstring checks. They complement rather than replace `make check`.
+
+## Documentation
+
+Reader documentation lives in `README.md` and `docs/`. Every page under `docs/`
+must be registered in `docs/manifest.json`. Generated sections and references
+must be refreshed with `make docs`; `make docs-check` (implemented as
+`scripts/generate_docs.py --check`) verifies that committed output matches a
+fresh deterministic render. See [Contributing documentation](docs/contributing-docs.md)
+for the rules governing pages, generated output, executable examples, and export
+lists.
+
+## What is accepted
+
+Changes should keep `make check` green, use US English, contain no AI or tool
+attribution, and preserve compatibility through additive changes where possible.
+Because the project is pre-1.0, an incompatible change may still be necessary;
+make its effect explicit and keep it as narrow as practical. See the
+[stability policy](README.md#stability).
+
+## Releases
+
+Releases are a maintainer operation. The package version has a single source of
+truth in `src/tiergraph/__init__.py`. Before release, maintainers run the full
+gate, build the distribution, verify the import reports the intended version,
+and wait for CI to pass. A GitHub Release whose `vX.Y.Z` tag matches the package
+version triggers the publish workflow; it builds the sdist and wheel and uploads
+them to PyPI through trusted publishing. PyPI releases cannot be overwritten.
+
+The complete operator checklist, including initial trusted-publisher setup,
+artifact checks, tagging, publication, and verification, is in
+[RELEASING.md](RELEASING.md).

tiergraph-0.1.0/LICENSE

@@ -0,0 +1,24 @@
+BSD 2-Clause License
+
+Copyright (c) 2026 Kevin Lenzo
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

tiergraph-0.1.0/Makefile

@@ -0,0 +1,59 @@
+VENV ?= .venv
+# Pin development to the supported floor so newer-only features cannot slip in.
+PYTHON ?= python3.12
+VENV_PYTHON := $(VENV)/bin/python
+
+.PHONY: venv lint format-check types test determinism-seed determinism schema schema-check docs docs-check tracked-clean documented check
+
+# Development happens in an isolated environment: a shared interpreter drags in
+# packages this project does not depend on, and they surface as type errors in
+# other people's stubs.
+venv: $(VENV)/bin/python
+
+$(VENV)/bin/python:
+	@$(PYTHON) -m venv $(VENV)
+	@$(VENV)/bin/pip install --quiet --upgrade pip
+	@$(VENV)/bin/pip install --quiet -e ".[dev]"
+
+lint:
+	@$(VENV_PYTHON) -m ruff check .
+
+format-check:
+	@$(VENV_PYTHON) -m ruff format --check .
+
+types:
+	@$(VENV_PYTHON) -m mypy
+
+test:
+	@$(VENV_PYTHON) -m pytest --cov=tiergraph --cov=tiergraph_dot --cov-report=term-missing
+
+# Separate processes: interpreter hash state is fixed at startup and cannot be
+# changed honestly inside one run.
+determinism-seed:
+	@test -n "$(HASH_SEED)" || (echo "HASH_SEED is required" >&2; exit 2)
+	@PYTHONHASHSEED=$(HASH_SEED) $(VENV_PYTHON) -m pytest
+
+determinism:
+	@for seed in 0 12345 999; do \
+		$(MAKE) --no-print-directory determinism-seed HASH_SEED=$$seed || exit $$?; \
+	done
+
+tracked-clean:
+	@$(VENV_PYTHON) scripts/check_tracked_clean.py
+
+documented:
+	@$(VENV_PYTHON) scripts/check_documented.py
+
+schema:
+	@$(VENV_PYTHON) scripts/generate_schema.py
+
+schema-check:
+	@$(VENV_PYTHON) scripts/generate_schema.py --check
+
+docs:
+	@$(VENV_PYTHON) scripts/generate_docs.py
+
+docs-check:
+	@$(VENV_PYTHON) scripts/generate_docs.py --check
+
+check: venv lint format-check types test determinism schema-check docs-check tracked-clean documented

tiergraph-0.1.0/PKG-INFO

@@ -0,0 +1,160 @@
+Metadata-Version: 2.5
+Name: tiergraph
+Version: 0.1.0
+Summary: Ordered tiers, declared relations, and an algebra over them
+Project-URL: Homepage, https://github.com/lenzo-ka/tiergraph
+Project-URL: Repository, https://github.com/lenzo-ka/tiergraph
+Author: Kevin Lenzo
+License-Expression: BSD-2-Clause
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Provides-Extra: dev
+Requires-Dist: hatchling>=1.27; extra == 'dev'
+Requires-Dist: hypothesis>=6.100; extra == 'dev'
+Requires-Dist: jsonschema>=4.26; extra == 'dev'
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pydantic>=2.9; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.16; extra == 'dev'
+Provides-Extra: lint
+Requires-Dist: mypy>=1.11; extra == 'lint'
+Requires-Dist: ruff>=0.16; extra == 'lint'
+Provides-Extra: test
+Requires-Dist: hypothesis>=6.100; extra == 'test'
+Requires-Dist: jsonschema>=4.26; extra == 'test'
+Requires-Dist: pytest-cov>=5.0; extra == 'test'
+Requires-Dist: pytest>=8.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# tiergraph
+
+*Ordered tiers, declared relations, and an algebra over them*
+
+tiergraph holds parallel ordered sequences and the declared links between them
+as one immutable graph, checked when it is built. Every view — selection,
+traversal, containment, timing, folds — is computed from that one graph, so no
+view can disagree with the store.
+
+The shape is the track view of an audio or video editor: rows of items, ordered
+within a row, aligned across rows, with links between rows. Aligned annotations
+over a signal have it; so do layered timelines and structured documents whose
+parts reference each other.
+
+You have this problem already if:
+
+- you can construct a state your own code treats as invalid;
+- you keep a derived index beside the store and must remember to update both; or
+- your serialized format breaks when you add a field.
+
+The package requires Python 3.12 or later. A PyPI release is not yet available;
+install it from a source checkout:
+
+```console
+git clone https://github.com/lenzo-ka/tiergraph.git
+cd tiergraph
+python -m pip install .
+tiergraph --version
+```
+
+## See an alignment
+
+This caption graph links each word to its phones. Select `cat`, walk the declared
+alignment, and the answer is visible in the input:
+
+```python
+from tiergraph import ItemSelector, Walk, WalkDirection, select
+from tiergraph.build import document
+
+builder = document("https://example.com/captions", prefix="caption")
+words = builder.tier(
+    "words",
+    ("a", "cat", "sat"),
+    item_type="word",
+    membership="word-membership",
+)
+phones = builder.tier(
+    "phones",
+    ("AH", "K", "AE", "T", "S", "AE-2", "T-2"),
+    item_type="phone",
+    membership="phone-membership",
+)
+aligns = builder.link(
+    "aligns",
+    words,
+    phones,
+    ((0, 0), (1, 1), (1, 2), (1, 3), (2, 4), (2, 5), (2, 6)),
+    acyclic=True,
+)
+graph = builder.build()
+
+cat = select(graph, (ItemSelector(graph, words.ref(1)),))
+reached = Walk(cat, aligns.name, WalkDirection.FORWARD).evaluate().nodes
+assert [node.reference for node in reached.nodes] == [
+    phones.ref(1),
+    phones.ref(2),
+    phones.ref(3),
+]
+```
+
+The complete runnable example keeps the displayed phone labels separate from
+their durable ids and prints `['K', 'AE', 'T']`; see
+[`examples/caption_alignment.py`](examples/caption_alignment.py).
+
+The model learned from Paul Hertz's Delta representation and the heterogeneous
+relation graphs (HRGs) of the Festival Speech Synthesis System. tiergraph keeps
+their emphasis on explicit tiered structure while defining a typed, immutable
+model and a versioned interchange format.
+
+Downstream migration (ipakit). ipakit is migrating onto tiergraph: Form's timed representation — units, intervals, positional lookup, and DOT rendering — is authoritative on the tiergraph library via a containment projection, with graph-independent identity hashing. The remaining backend subsystem graphs (such as pronunciation/CMU, mora, pinyin, gesture, and rewrite) and their JSON wire are still on ipakit's embedded graph engine and are being migrated to the library; when that completes the embedded engine is removed.
+
+## What you can do with it
+
+- Build a graph directly, or record an ordered edit stream as a `Program` and run
+  it — see [construction](docs/guide/construction.md).
+- Select and traverse the structure, including ordered containment — see
+  [selection and traversal](docs/guide/selection-and-traversal.md).
+- Fold a dependency graph with a semiring to measure or recognize it — see
+  [folding](docs/guide/folding.md) and [recognize and act](docs/guide/recognize-and-act.md).
+- Attach a clock profile and resolve physical timing — see [timing](docs/guide/timing.md).
+- Serialize to canonical JSON or render Graphviz DOT — see
+  [serialization](docs/guide/serialization.md).
+- Project segmentation graphs into deterministic span views for JSON, JSON Lines,
+  text, HTML, or DOT — see [span views](docs/guide/span-views.md).
+
+## Documentation
+
+Start with the [documentation map](docs/README.md), then
+[concepts](docs/concepts.md) for the data model and [getting
+started](docs/getting-started.md) for a worked walkthrough. The [API
+reference](docs/reference/api.md) covers every top-level export; the [CLI
+reference](docs/reference/cli.md) is generated from the parser.
+
+The companion `tiergraph_dot` package renders a graph as deterministic Graphviz
+DOT and ships in the same distribution:
+
+```python
+import tiergraph_dot
+
+dot = tiergraph_dot.dumps(graph)
+```
+
+## Stability
+
+tiergraph 0.1.x is alpha software. The public Python API may change before 1.0;
+where possible, changes will be additive, but compatibility is not yet promised.
+The JSON wire format, construction machine format, and span-view JSON format
+carry explicit version stamps so a reader can identify the format it receives.
+A format stamp identifies a contract; it does not imply that every version can
+read or migrate every older format.
+
+After 1.0, the intended policy is to announce a deprecated public Python API in
+a minor release, retain it with a warning for at least one subsequent minor
+release, and remove it only in a later release. Security, correctness, or
+otherwise impractical compatibility constraints may require a faster change,
+which will be documented in the release. This is an intended post-1.0 policy,
+not a compatibility promise for the current alpha series.

tiergraph-0.1.0/README.md

@@ -0,0 +1,127 @@
+# tiergraph
+
+*Ordered tiers, declared relations, and an algebra over them*
+
+tiergraph holds parallel ordered sequences and the declared links between them
+as one immutable graph, checked when it is built. Every view — selection,
+traversal, containment, timing, folds — is computed from that one graph, so no
+view can disagree with the store.
+
+The shape is the track view of an audio or video editor: rows of items, ordered
+within a row, aligned across rows, with links between rows. Aligned annotations
+over a signal have it; so do layered timelines and structured documents whose
+parts reference each other.
+
+You have this problem already if:
+
+- you can construct a state your own code treats as invalid;
+- you keep a derived index beside the store and must remember to update both; or
+- your serialized format breaks when you add a field.
+
+The package requires Python 3.12 or later. A PyPI release is not yet available;
+install it from a source checkout:
+
+```console
+git clone https://github.com/lenzo-ka/tiergraph.git
+cd tiergraph
+python -m pip install .
+tiergraph --version
+```
+
+## See an alignment
+
+This caption graph links each word to its phones. Select `cat`, walk the declared
+alignment, and the answer is visible in the input:
+
+```python
+from tiergraph import ItemSelector, Walk, WalkDirection, select
+from tiergraph.build import document
+
+builder = document("https://example.com/captions", prefix="caption")
+words = builder.tier(
+    "words",
+    ("a", "cat", "sat"),
+    item_type="word",
+    membership="word-membership",
+)
+phones = builder.tier(
+    "phones",
+    ("AH", "K", "AE", "T", "S", "AE-2", "T-2"),
+    item_type="phone",
+    membership="phone-membership",
+)
+aligns = builder.link(
+    "aligns",
+    words,
+    phones,
+    ((0, 0), (1, 1), (1, 2), (1, 3), (2, 4), (2, 5), (2, 6)),
+    acyclic=True,
+)
+graph = builder.build()
+
+cat = select(graph, (ItemSelector(graph, words.ref(1)),))
+reached = Walk(cat, aligns.name, WalkDirection.FORWARD).evaluate().nodes
+assert [node.reference for node in reached.nodes] == [
+    phones.ref(1),
+    phones.ref(2),
+    phones.ref(3),
+]
+```
+
+The complete runnable example keeps the displayed phone labels separate from
+their durable ids and prints `['K', 'AE', 'T']`; see
+[`examples/caption_alignment.py`](examples/caption_alignment.py).
+
+The model learned from Paul Hertz's Delta representation and the heterogeneous
+relation graphs (HRGs) of the Festival Speech Synthesis System. tiergraph keeps
+their emphasis on explicit tiered structure while defining a typed, immutable
+model and a versioned interchange format.
+
+Downstream migration (ipakit). ipakit is migrating onto tiergraph: Form's timed representation — units, intervals, positional lookup, and DOT rendering — is authoritative on the tiergraph library via a containment projection, with graph-independent identity hashing. The remaining backend subsystem graphs (such as pronunciation/CMU, mora, pinyin, gesture, and rewrite) and their JSON wire are still on ipakit's embedded graph engine and are being migrated to the library; when that completes the embedded engine is removed.
+
+## What you can do with it
+
+- Build a graph directly, or record an ordered edit stream as a `Program` and run
+  it — see [construction](docs/guide/construction.md).
+- Select and traverse the structure, including ordered containment — see
+  [selection and traversal](docs/guide/selection-and-traversal.md).
+- Fold a dependency graph with a semiring to measure or recognize it — see
+  [folding](docs/guide/folding.md) and [recognize and act](docs/guide/recognize-and-act.md).
+- Attach a clock profile and resolve physical timing — see [timing](docs/guide/timing.md).
+- Serialize to canonical JSON or render Graphviz DOT — see
+  [serialization](docs/guide/serialization.md).
+- Project segmentation graphs into deterministic span views for JSON, JSON Lines,
+  text, HTML, or DOT — see [span views](docs/guide/span-views.md).
+
+## Documentation
+
+Start with the [documentation map](docs/README.md), then
+[concepts](docs/concepts.md) for the data model and [getting
+started](docs/getting-started.md) for a worked walkthrough. The [API
+reference](docs/reference/api.md) covers every top-level export; the [CLI
+reference](docs/reference/cli.md) is generated from the parser.
+
+The companion `tiergraph_dot` package renders a graph as deterministic Graphviz
+DOT and ships in the same distribution:
+
+```python
+import tiergraph_dot
+
+dot = tiergraph_dot.dumps(graph)
+```
+
+## Stability
+
+tiergraph 0.1.x is alpha software. The public Python API may change before 1.0;
+where possible, changes will be additive, but compatibility is not yet promised.
+The JSON wire format, construction machine format, and span-view JSON format
+carry explicit version stamps so a reader can identify the format it receives.
+A format stamp identifies a contract; it does not imply that every version can
+read or migrate every older format.
+
+After 1.0, the intended policy is to announce a deprecated public Python API in
+a minor release, retain it with a warning for at least one subsequent minor
+release, and remove it only in a later release. Security, correctness, or
+otherwise impractical compatibility constraints may require a faster change,
+which will be documented in the release. This is an intended post-1.0 policy,
+not a compatibility promise for the current alpha series.