tiergraph 0.2.0__tar.gz → 0.2.2__tar.gz

{tiergraph-0.2.0 → tiergraph-0.2.2}/CHANGELOG.md

@@ -7,6 +7,87 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.2] - 2026-09-14
+
+### Added
+
+- Added `LOG_PROBABILITY`, the log-sum-exp semiring over finite IEEE-double log
+  weights with `-inf` as its zero: stable addition, log-product multiplication,
+  positive weights admitted, overflow refused, every required law except
+  addition commutativity declared approximate, and no star. `tiergraph semirings` lists it as
+  `log-probability`, and `tiergraph fold --semiring log-probability` runs it.
+  Its `normalize` method is the declared readout that turns log weights into
+  probabilities of a total; `ExpectationSemiring` still refuses this inexact
+  base (#186).
+- Added `PathPlan`, which compiles a `FoldDeclaration` over one `OR` relation on
+  an acyclic graph once and evaluates it again under any vector of carrier
+  values in the plan's item order. `evaluate` reproduces what `run` returns for
+  the same values, with the same provenance and cost account: exactly under the
+  `ARCTIC` and `TROPICAL` carriers, and within the algebra's declared
+  approximation under `LOG_PROBABILITY`, where a gathered log-sum-exp sums its
+  exponentials in a different order than pairwise addition does. `marginals`
+  adds the outside pass and returns `PathMarginals`, whose
+  `posteriors(readout=...)` reads probabilities through the readout the caller
+  declares and the algebra publishes, and reports zero mass rather than
+  fabricating a distribution, as `PathPosteriors` with the readout named. Under
+  those three carriers the plan runs the algebra's operations in a fused
+  schedule when the declaration states no witness order, and under the extremum
+  carriers also under an `AlgebraOrder` — a witness order by an algebra's own
+  selective addition — with `CHOOSE_FIRST`, whose selection it fuses too; every
+  other declaration runs the general schedule. Ranked output, index axes,
+  several relations, `AND` transitions, and cycles are refused by name (#186).
+
+### Changed
+
+- The package root now exports every semiring constant the shell can name:
+  `ARCTIC`, `DECIMAL_ARCTIC`, `LOG_PROBABILITY` and `TROPICAL` join `BOOLEAN`,
+  `COUNTING`, `DECIMAL_TROPICAL` and `PATH` there. `PATH_WITNESSES`, which the
+  shell has no spelling for, stays on `tiergraph.semiring`, as every constant
+  still does (#186).
+- `FoldDeclaration` now states where a readout above the algebra is declared,
+  and the `declared-readout` reservation is discharged: the reservation
+  register carries four entries, and `PathMarginals.posteriors` records the
+  readout it applies (#186).
+- The gate's three hash-seed test passes run concurrently under `make
+  determinism`; `DETERMINISM_JOBS=1` runs them one at a time, and each seed
+  writes its own log under the virtualenv and prints only its summary line when
+  it passes; a failing seed prints its whole log.
+  The publishability test that plants a sentinel under the checkout's ignored
+  local agent directory names it per process, so concurrent passes over one
+  checkout no longer race on its cleanup (#187).
+- The schema-codec conformance suite audits its generated probes once per
+  module and subtracts each test's policy from that audit, through the
+  harness's new `audit_drifts` and `subtract_declared`, whose composition
+  `undeclared_drifts` still is; a test holds the two answers equal. The three
+  tests that each ran the full audit took most of the suite's time (#187).
+- `FORMAT_VERSION` stays `"0.2.0"`: nothing in this line touches the wire
+  format, and `make format-growth` reports no break.
+
+### Documentation
+
+- The release runbook's step 3 no longer says a stale local `dist/` build is
+  what the publish workflow would upload; the workflow builds from a fresh
+  checkout of the tag. It now separates the two local checks: the wheel package
+  listing reads `dist/*.whl`, so a stale archive is what it would read, while
+  the printed version imports from `src` and never consults `dist/` at all. The
+  `dist/` filename listing is the only step that would expose a stale build, as
+  an extra pair of archives (#185).
+
+## [0.2.1] - 2026-09-13
+
+### Added
+
+- Added `embed_json_value` to embed a native JSON value in an existing graph
+  through an explicitly fresh namespace. It returns the extended graph, its
+  validated value profile, and the value root while preserving the source
+  graph. Namespace collisions refuse without partial changes; owner relations
+  remain caller-declared. The graph interchange format is unchanged (#183).
+
+### Documentation
+
+- Clarified that release-phase format-growth regression tests must consult
+  tags, so the release tag does not invalidate their expectations (#182).
+
 ## [0.2.0] - 2026-09-05
 
 ### Highlights
@@ -881,6 +962,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - 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.
 
-[Unreleased]: https://github.com/lenzo-ka/tiergraph/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/lenzo-ka/tiergraph/compare/v0.2.2...HEAD
+[0.2.2]: https://github.com/lenzo-ka/tiergraph/compare/v0.2.1...v0.2.2
+[0.2.1]: https://github.com/lenzo-ka/tiergraph/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/lenzo-ka/tiergraph/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/lenzo-ka/tiergraph/releases/tag/v0.1.0

{tiergraph-0.2.0 → tiergraph-0.2.2}/CONTRIBUTING.md

@@ -52,7 +52,10 @@ version this section used to carry fell a step behind twice: a copied list is a
 claim about the gate that nothing checks.
 
 `make check` builds the virtualenv and then runs `make gate`, which is the same
-steps against an environment that already exists. Run `gate` where an index
+steps against an environment that already exists. The `determinism` step runs
+its three seeds concurrently, each writing a log under the virtualenv and
+printing its summary line; on a machine that cannot hold three interpreters at
+once, `make gate DETERMINISM_JOBS=1` runs them one at a time. Run `gate` where an index
 cannot be reached, rather than copying its steps out by hand. Coverage is
 measured for the `tiergraph` and `tiergraph_dot` packages and for the `scripts`
 gates, and must remain at 100% branch coverage.

{tiergraph-0.2.0 → tiergraph-0.2.2}/Makefile

@@ -26,7 +26,7 @@ export PYTHONPATH := $(MAKEFILE_DIR)/src$(if $(PYTHONPATH),:$(PYTHONPATH))
 # and runs nothing. A target left off this line is silent until something in the
 # tree happens to share its name, which is why `format-semantics` and
 # `corpus-capture` sat missing here without ever being noticed.
-.PHONY: venv lint format-check types test determinism-seed determinism schema schema-check format-growth format-semantics corpus-capture docs docs-check tracked-clean documented reservations changelog-claims gate-fast gate check
+.PHONY: venv lint format-check types test determinism-seed determinism determinism-seed-0 determinism-seed-12345 determinism-seed-999 schema schema-check format-growth format-semantics corpus-capture docs docs-check tracked-clean documented reservations changelog-claims gate-fast gate 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
@@ -56,10 +56,26 @@ determinism-seed:
 	@test -n "$(HASH_SEED)" || (echo "HASH_SEED is required" >&2; exit 2)
 	@PYTHONHASHSEED=$(HASH_SEED) $(VENV_PYTHON) -m pytest
 
+# The three seeds are independent, so they run concurrently: measured serial,
+# they were the larger half of the gate's wall time. Each seed writes its own
+# log under the virtualenv (ignored, so it cannot ship) and prints only its
+# summary line, so three interleaved dot streams do not have to be read. A
+# failing seed prints its whole log. DETERMINISM_JOBS=1 runs them one at a
+# time on a machine that cannot hold three interpreters at once.
+DETERMINISM_JOBS ?= 3
+DETERMINISM_SEEDS := 0 12345 999
+
 determinism:
-	@for seed in 0 12345 999; do \
-		$(MAKE) --no-print-directory determinism-seed HASH_SEED=$$seed || exit $$?; \
-	done
+	@$(MAKE) --no-print-directory -j$(DETERMINISM_JOBS) \
+		$(addprefix determinism-seed-,$(DETERMINISM_SEEDS))
+
+determinism-seed-0 determinism-seed-12345 determinism-seed-999:
+	@seed=$(@:determinism-seed-%=%); log=$(VENV)/determinism-$$seed.log; \
+	if $(MAKE) --no-print-directory determinism-seed HASH_SEED=$$seed >$$log 2>&1; then \
+		printf 'seed %s: %s\n' "$$seed" "$$(tail -n 1 $$log)"; \
+	else \
+		status=$$?; cat $$log; echo "seed $$seed failed" >&2; exit $$status; \
+	fi
 
 tracked-clean:
 	@$(VENV_PYTHON) scripts/check_tracked_clean.py

{tiergraph-0.2.0 → tiergraph-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: tiergraph
-Version: 0.2.0
+Version: 0.2.2
 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

{tiergraph-0.2.0 → tiergraph-0.2.2}/RELEASING.md

@@ -82,7 +82,11 @@ job references it; the OIDC identity is scoped to it).
    opened the release line, and this edit is what leaves something for that
    commit.
 
-3. **Verify locally.** Run these from the development virtualenv that
+3. **Regenerate version-bearing documentation, then verify locally.** Run
+   `make docs` after changing the package version: the generated API and CLI
+   references carry it. Commit those generated changes with the
+   release preparation so the gate checks the documentation that will ship.
+   Run these from the development virtualenv that
    [CONTRIBUTING.md](CONTRIBUTING.md#set-up-a-development-environment) builds —
    `make venv` creates `.venv` and installs the `build` frontend along with the
    rest of the development dependencies. Three of these steps are **read**, not
@@ -113,8 +117,9 @@ job references it; the OIDC identity is scoped to it).
      displaying it — so without this line the doc asks for a comparison it
      gives no way to make. Expect exactly `tiergraph-X.Y.Z.tar.gz` and
      `tiergraph-X.Y.Z-py3-none-any.whl`; a stale build left in `dist/` from an
-     earlier version shows up here as an extra pair, and it is what the publish
-     workflow would upload.
+     earlier version shows up here as an extra pair. The publish workflow never
+     sees it — it builds from a fresh checkout of the tag — but the local
+     checks below would read the wrong archive.
    - **The wheel listing must show both packages.** The grep exits 0 when
      either package is present, so the exit status decides nothing: read the
      output and confirm entries under `tiergraph/` *and* under `tiergraph_dot/`.
@@ -255,6 +260,7 @@ ascending sort order.
   still exists, before `rm -rf dist build` removes it. That listing is read, not
   scored: the pattern matches either package, so *both* is a fact about the
   output rather than about the exit status.
+- **Tag-sensitive format-growth tests**: A regression test that asserts what `format-growth` reports is phase-dependent: the report changes the moment the line's first tag exists. Such a test must read the phase from the tags, as `test_the_committed_schema_reports_only_the_break_this_release_priced` does, or it fails on the release commit once tagged; the tag goes up with the release commit in step 4, and the CI run that must be green before step 5 checks out full history and tags, so it sees the tag and a test depending on the tag's absence fails there.
 - **CI must be green first**: `ci.yml` runs on the push; only cut the release
   once it passes.
 - **Re-releases**: PyPI is immutable — you cannot overwrite `X.Y.Z`. If a build

{tiergraph-0.2.0 → tiergraph-0.2.2}/docs/concepts.md

@@ -121,11 +121,15 @@ or schema is present or recognized; required fields or types inside `value`;
 numeric ranges; or canonical serialization. The producing and consuming
 applications must perform those validations.
 
-Separately, `json_value_graph` and `JsonValueProfile` already represent a JSON
-value as a checked, standalone graph. They are the foundation for a future
-first-class payload-attachment API that could attach a JSON value to an item in
-another graph. That API does not yet exist. If it is added, stringified-JSON
-attributes will be candidates for migration.
+Separately, `json_value_graph` and `JsonValueProfile` represent a JSON value as
+a checked, standalone graph. `embed_json_value(graph, value, namespace=...)`
+adds that native structure to an existing graph and returns the extended graph,
+validated profile, and root reference. Supply a `NamespaceDeclaration` with an
+unused URI and prefix; collisions refuse rather than rename or overwrite.
+Existing facts remain unchanged, including boundaries, seals, and layers.
+The helper does not infer an owner: link the returned root through your own
+declared relation. It is not an arbitrary graph merge or an automatic migration
+of stringified-JSON attributes.
 
 ## Coordinates, and what an edit does to them
 

{tiergraph-0.2.0 → tiergraph-0.2.2}/docs/guide/folding.md

@@ -335,6 +335,204 @@ Use `TROPICAL` or `ARCTIC`, whose associativity check is approximate, for
 `xsd:double` values. The refusal is a declaration-time guard, so a fold that
 runs has already been checked for this mismatch.
 
+## Preparing a path plan
+
+A fold over one `OR` relation on an acyclic graph is a path graph: every
+derivation is a root-to-sink path, and its value is the product of the local
+values along it. When the graph stays fixed and only the values change — an
+expectation step re-weighting the same lattice, a sweep over parameters —
+`PathPlan` compiles the declaration's topology once and evaluates it under any
+vector of carrier values given in the plan's item order. `PathPlan.evaluate`
+returns what `FoldDeclaration.run` returns, provenance and cost account
+included, and `PathPlan.marginals` adds the outside pass: for every item, the
+sum over the derivations that pass through it.
+
+The example is a small lattice whose states and arcs are items of one tier,
+joined by a `next` relation, with the arcs after the states. Under
+`LOG_PROBABILITY` the values are log weights and `-INF` is the zero. A sink
+accepts with its own value, so the final state carries `0.0` and a dead end
+would carry `-INF`.
+
+```python
+import math
+
+from tiergraph import (
+    AttributeDeclaration,
+    AttributeDomain,
+    AttributeValuation,
+    AttributeValue,
+    BipartiteRelationDeclaration,
+    ChildCombination,
+    FoldDeclaration,
+    FoldTransition,
+    Graph,
+    Item,
+    ItemRef,
+    NamespaceDeclaration,
+    QualifiedName,
+    RelationInstance,
+    SimpleRelationDeclaration,
+    Tier,
+    TierDeclaration,
+    TiePolicy,
+    XsdType,
+)
+from tiergraph.pathplan import AlgebraOrder, PathPlan
+from tiergraph.semiring import ARCTIC, LOG_PROBABILITY
+
+ns = "https://example.com/plan"
+nodes = QualifiedName(ns, "nodes")
+node = QualifiedName(ns, "node")
+follows = QualifiedName(ns, "next")
+weight = QualifiedName(ns, "weight")
+
+
+def item(label: str, log_weight: float) -> Item:
+    lexical = "-INF" if log_weight == -math.inf else repr(log_weight)
+    return Item(label, (AttributeValue(weight, XsdType.DOUBLE, lexical),))
+
+
+labels = ("s", "m", "f", "merged", "first", "silent")
+lattice_refs = {label: ItemRef(nodes, index) for index, label in enumerate(labels)}
+graph = Graph(
+    (NamespaceDeclaration("lattice", ns),),
+    (
+        Tier(
+            TierDeclaration(nodes, "States and arcs"),
+            (
+                item("s", 0.0),
+                item("m", 0.0),
+                item("f", 0.0),
+                item("merged", math.log(0.4)),
+                item("first", math.log(0.3)),
+                item("silent", math.log(0.5)),
+            ),
+        ),
+    ),
+    (
+        SimpleRelationDeclaration(QualifiedName(ns, "membership"), nodes, node),
+        BipartiteRelationDeclaration(follows, node, node, acyclic=True),
+    ),
+    tuple(
+        RelationInstance(follows, lattice_refs[left], lattice_refs[right])
+        for left, right in (
+            ("s", "merged"),
+            ("merged", "f"),
+            ("s", "first"),
+            ("first", "m"),
+            ("m", "silent"),
+            ("silent", "f"),
+        )
+    ),
+    (AttributeDeclaration(weight, AttributeDomain.ITEM, XsdType.DOUBLE),),
+)
+valuation = AttributeValuation("weight", weight, (nodes,))
+transitions = (FoldTransition(follows, ChildCombination.OR),)
+
+plan = PathPlan.prepare(
+    FoldDeclaration(
+        "lattice",
+        graph,
+        valuation,
+        LOG_PROBABILITY,
+        lambda value, _label: value,
+        transitions,
+        roots=(lattice_refs["s"],),
+    )
+)
+marginals = plan.marginals()
+print("log mass:", round(marginals.total, 6))
+posteriors = marginals.posteriors(readout="normalize")
+print("readout:", posteriors.readout)
+probabilities = posteriors.values
+assert probabilities is not None  # zero mass is reported, never fabricated
+for label, probability in zip(plan.labels, probabilities):
+    print(f"{label}: {probability:.4f}")
+```
+
+```text
+log mass: -0.597837
+readout: normalize
+s: 1.0000
+m: 0.2727
+f: 1.0000
+merged: 0.7273
+first: 0.2727
+silent: 0.2727
+```
+
+The mass is `0.4 + 0.3 × 0.5 = 0.55`, and each posterior is the share of that
+mass passing through the item. Normalizing is a division above the algebra,
+so the caller declares the readout by name and the carrier must publish it —
+`normalize` is the one `LOG_PROBABILITY` publishes — and `PathPosteriors`
+records the readout it applied. A zero total is reported as `zero_mass` with
+no values rather than as a fabricated distribution. Aggregating
+posteriors by anything other than item — by the output an arc emits, say — is
+the caller's readout in turn; two arcs producing the same output each carry
+their own share here.
+
+New values reuse the compiled topology. `plan.values` holds what the
+declaration lifted, `plan.index` locates an item's position, and a vector of
+another length is refused:
+
+```python
+reweighted = list(plan.values)
+reweighted[plan.index(lattice_refs["merged"])] = math.log(0.1)
+print("re-weighted log mass:", round(plan.marginals(reweighted).total, 6))
+```
+
+```text
+re-weighted log mass: -1.386294
+```
+
+A best path runs the same plan under a selective carrier. `AlgebraOrder` is a
+witness order by the algebra's own addition, so the fold and the plan agree on
+what wins; with `CHOOSE_FIRST` a tie goes to the alternative earliest in the
+graph's canonical order, deterministically, and `ALL` keeps every tied path up
+to `output_cap`.
+
+```python
+best = PathPlan.prepare(
+    FoldDeclaration(
+        "best",
+        graph,
+        valuation,
+        ARCTIC,
+        lambda value, _label: value,
+        transitions,
+        roots=(lattice_refs["s"],),
+        witness_order=AlgebraOrder(ARCTIC),
+        tie_policy=TiePolicy.CHOOSE_FIRST,
+    )
+)
+result = best.evaluate()
+print("best:", round(result.value, 6), result.provenance)
+print("carrier ops:", result.cost.carrier_work)
+```
+
+```text
+best: -0.916291 (('s', 'merged', 'f'),)
+carrier ops: 8
+```
+
+Under `LOG_PROBABILITY`, `ARCTIC`, and `TROPICAL` the plan runs a fused
+schedule that gathers each item's alternatives at once with the algebra's
+operations inlined, and an `AlgebraOrder` with `CHOOSE_FIRST` fuses the
+selection too. The cost account is the general schedule's. A gathered
+log-sum-exp sums its exponentials in a different order than pairwise
+addition, so under the log carrier the plan agrees with `run` within the
+algebra's declared approximation — at the rounding scale of the operands,
+which a total near cancellation can show in its result — and under the
+extremum carriers exactly. Every other declaration runs the general schedule
+through the algebra's methods and agrees with `run` exactly. A result
+that would leave the finite double carrier is refused as overflow rather than
+read as mass created or destroyed, and a value vector outside the carrier —
+`NaN`, a Boolean, the excluded infinity — is refused before anything runs.
+
+A plan refuses what a path cannot carry, each by name: ranked output, an index
+product, more than one dependency relation, an `AND` transition, and a cycle,
+which is reported by its closing edge.
+
 ## From the command line
 
 `tiergraph semirings` lists the algebras the `tiergraph fold` shell can name,

{tiergraph-0.2.0 → tiergraph-0.2.2}/docs/manifest.json

@@ -38,6 +38,7 @@
       "GraphEditor"
     ],
     "fold": [
+      "AlgebraOrder",
       "AttributeValuation",
       "ChildCombination",
       "ExactnessRefusal",
@@ -48,6 +49,9 @@
       "FoldHomomorphism",
       "FoldResult",
       "FoldTransition",
+      "PathMarginals",
+      "PathPlan",
+      "PathPosteriors",
       "TiePolicy"
     ],
     "grammar": [
@@ -147,6 +151,7 @@
       "RoleBinding",
       "RoleValue",
       "SpanViewProfile",
+      "embed_json_value",
       "json_value_graph",
       "span_view",
       "to_html",
@@ -195,10 +200,14 @@
       "selection_loads"
     ],
     "semirings": [
+      "ARCTIC",
       "BOOLEAN",
       "COUNTING",
+      "DECIMAL_ARCTIC",
       "DECIMAL_TROPICAL",
+      "LOG_PROBABILITY",
       "PATH",
+      "TROPICAL",
       "StarRefusal",
       "StarSelector",
       "ZeroClosedStar"
@@ -297,6 +306,12 @@
       "text",
       "python",
       "text",
+      "python",
+      "text",
+      "python",
+      "text",
+      "python",
+      "text",
       "console"
     ],
     "docs/guide/profiles.md": [
@@ -378,6 +393,7 @@
       "COUNTING",
       "DECIMAL_ARCTIC",
       "DECIMAL_TROPICAL",
+      "LOG_PROBABILITY",
       "PATH",
       "PATH_WITNESSES",
       "TROPICAL",
@@ -389,6 +405,7 @@
       "ExpectationSemiring",
       "LawCheck",
       "LexicographicSemiring",
+      "LogProbabilitySemiring",
       "Path",
       "PathSemiring",
       "PathValue",