tiergraph 0.2.2__tar.gz → 0.2.3__tar.gz

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

@@ -7,6 +7,39 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.3] - 2026-09-15
+
+### Added
+
+- Added `Emissions` and `OutputPlan`, which pool the mass of complete paths by
+  the output string their items emit, over candidates the caller supplies, beside
+  `PathPlan` and without changing it. `OutputPlan.masses` returns `OutputMasses`:
+  each candidate's mass and the residual mass of every other output, computed in
+  the base algebra by one marginal pass rather than by subtraction, with the zero
+  mass reported rather than a distribution fabricated. Its `decided` and `tied`
+  certificates are available only under `LOG_PROBABILITY` and `COUNTING`; under
+  `LOG_PROBABILITY`, `tied` compares computed values, which an approximate
+  algebra can split for equal real masses. `conditioned` restricts the plan to
+  paths accepted as one candidate, refused only when no such path exists, and
+  `item_marginals` pools those conditioned marginals back to the base plan's
+  items as `OutputItemMarginals`. Declared roots and relation-instance
+  multiplicity carry into the derived plan. Duplicate or empty candidate sets,
+  invalid emissions, and noncommutative multiplication are refused. The pooled
+  best output over all strings is intractable in general, so the plan scores the
+  candidates it is given and reports the residual that bounds every other (#190).
+
+### Changed
+
+- `FORMAT_VERSION` stays `"0.2.0"`: nothing in this line touches the wire
+  format, and `make format-growth` reports no break.
+
+### Documentation
+
+- The lineage now credits Sue Hertz for the Delta representation, which the
+  README and the concepts guide had attributed to Paul Hertz, and spells out
+  Heterogeneous Relation Graphs (HRGs) (#189). The README no longer claims that no
+  view can disagree with the store.
+
 ## [0.2.2] - 2026-09-14
 
 ### Added
@@ -962,7 +995,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.2...HEAD
+[Unreleased]: https://github.com/lenzo-ka/tiergraph/compare/v0.2.3...HEAD
+[0.2.3]: https://github.com/lenzo-ka/tiergraph/compare/v0.2.2...v0.2.3
 [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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: tiergraph
-Version: 0.2.2
+Version: 0.2.3
 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
@@ -38,8 +38,7 @@ Description-Content-Type: text/markdown
 
 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.
+traversal, containment, timing, folds — is computed from that one graph.
 
 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
@@ -110,8 +109,8 @@ 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
+The model is informed by Sue 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.
 

{tiergraph-0.2.2 → tiergraph-0.2.3}/README.md

@@ -4,8 +4,7 @@
 
 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.
+traversal, containment, timing, folds — is computed from that one graph.
 
 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
@@ -76,8 +75,8 @@ 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
+The model is informed by Sue 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.
 

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

@@ -266,8 +266,8 @@ declarations that interpretation needs and refuses a graph that cannot carry it.
 
 ## Lineage
 
-The model learned from Paul Hertz's Delta representation and the heterogeneous
-relation graphs of the Festival Speech Synthesis System. tiergraph keeps their
+The model is informed by Sue Hertz's Delta representation and the Heterogeneous
+Relation Graphs (HRGs) of the Festival Speech Synthesis System. tiergraph keeps their
 emphasis on explicit tiered structure and defines its own typed, immutable
 model with a versioned interchange format. Phonetics is one application; the
 graph and format assign no phonetic meaning to any tier or attribute.

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

@@ -49,6 +49,10 @@
       "FoldHomomorphism",
       "FoldResult",
       "FoldTransition",
+      "Emissions",
+      "OutputItemMarginals",
+      "OutputMasses",
+      "OutputPlan",
       "PathMarginals",
       "PathPlan",
       "PathPosteriors",

{tiergraph-0.2.2 → tiergraph-0.2.3}/docs/reference/api.md

@@ -1,7 +1,7 @@
 # API reference
 
 This page is generated from the shipped objects and the documentation manifest.
-It covers 202 top-level `tiergraph` exports exactly once.
+It covers 206 top-level `tiergraph` exports exactly once.
 
 ## Action
 
@@ -1337,6 +1337,125 @@ FoldTransition(relation: 'QualifiedName', combination: 'ChildCombination') -> No
 
 Give one dependency relation its local AND/OR incidence meaning.
 
+### `Emissions`
+
+```text
+Emissions(plan: 'PathPlan[Value]', per_item: 'tuple[tuple[str, ...], ...]') -> None
+```
+
+Per-item token tuples bound to one path plan's label inventory.
+
+#### `Emissions.bind`
+
+Class method.
+
+```text
+Emissions.bind(cls, plan: 'PathPlan[Value]', by_label: 'Mapping[str, Sequence[str]]') -> 'Emissions[Value]'
+```
+
+Bind emissions by item label, leaving unlisted items non-emitting.
+
+### `OutputItemMarginals`
+
+```text
+OutputItemMarginals(total: 'Value', zero_mass: 'bool', values: 'tuple[Value, ...] | None', cost: 'FoldCost') -> None
+```
+
+Conditioned marginals pooled into the base plan's item order.
+
+#### `OutputItemMarginals.to_data`
+
+Method.
+
+```text
+OutputItemMarginals.to_data(self, semiring: 'Semiring[Value]') -> 'dict[str, object]'
+```
+
+Return deterministic strict-JSON data using the carrier encoding.
+
+### `OutputMasses`
+
+```text
+OutputMasses(total: 'Value', per_candidate: 'tuple[Value, ...]', residual: 'Value', zero_mass: 'bool', decided: 'bool | None', tied: 'tuple[int, ...] | None', cost: 'FoldCost') -> None
+```
+
+Candidate and residual masses from one product-plan marginal pass.
+
+``decided`` and ``tied`` are available only for ``LOG_PROBABILITY`` and
+``COUNTING`` because their numeric order gives the certificate its meaning;
+both are ``None`` under other algebras. Counting ties use exact integer
+equality. Log-probability ties use equality of the computed doubles, so an
+approximate addition can split equal real masses and ``tied`` is not a tie
+certificate for the underlying real values.
+
+#### `OutputMasses.to_data`
+
+Method.
+
+```text
+OutputMasses.to_data(self, semiring: 'Semiring[Value]') -> 'dict[str, object]'
+```
+
+Return deterministic strict-JSON data using the carrier encoding.
+
+### `OutputPlan`
+
+```text
+OutputPlan(base: 'PathPlan[Value]', emissions: 'Emissions[Value]', candidates: 'tuple[tuple[str, ...], ...]', plan: 'PathPlan[Value]', base_index: 'Mapping[ItemRef, ItemRef]', accepted: 'tuple[bool, ...]', _product_base: 'tuple[int | None, ...]', _accept_indices: 'tuple[int, ...]', _residual_index: 'int', _conditioned_cache: 'dict[int, tuple[PathPlan[Value], tuple[int, ...]]]' = <factory>) -> None
+```
+
+A cached product plan for complete output candidates and their residual.
+
+#### `OutputPlan.prepare`
+
+Class method.
+
+```text
+OutputPlan.prepare(cls, base: 'PathPlan[Value]', emissions: 'Emissions[Value]', candidates: 'Sequence[Sequence[str]]') -> 'OutputPlan[Value]'
+```
+
+Build the reachable product with the candidates' trie and a residual.
+
+#### `OutputPlan.values`
+
+Method.
+
+```text
+OutputPlan.values(self, base_values: 'Sequence[Value] | None' = None) -> 'tuple[Value, ...]'
+```
+
+Gather base values into the product plan's canonical item order.
+
+#### `OutputPlan.masses`
+
+Method.
+
+```text
+OutputPlan.masses(self, base_values: 'Sequence[Value] | None' = None) -> 'OutputMasses[Value]'
+```
+
+Evaluate masses, with certificates only for log probability or counting.
+
+#### `OutputPlan.conditioned`
+
+Method.
+
+```text
+OutputPlan.conditioned(self, candidate: 'int') -> 'PathPlan[Value]'
+```
+
+Return the product restricted to paths accepting one candidate.
+
+#### `OutputPlan.item_marginals`
+
+Method.
+
+```text
+OutputPlan.item_marginals(self, candidate: 'int', base_values: 'Sequence[Value] | None' = None) -> 'OutputItemMarginals[Value]'
+```
+
+Pool one candidate's conditioned product copies onto base items.
+
 ### `PathMarginals`
 
 ```text
@@ -2845,7 +2964,7 @@ Canonical complete-boundary grammar value. Current value: `AttributeValue(name=Q
 
 ### `__version__`
 
-Installed distribution version. Current value: `0.2.2`.
+Installed distribution version. Current value: `0.2.3`.
 
 ## Paths
 
@@ -4782,7 +4901,7 @@ Return strict-JSON traversal data in canonical node order.
 
 ### `tiergraph.build`
 
-This module is importable and usable, but carries no API-stability promise at version 0.2.2.
+This module is importable and usable, but carries no API-stability promise at version 0.2.3.
 
 Builder notation errors raise the directly importable `tiergraph.build.BuilderError`, a `ValueError` subclass. It is not part of the module's star-exported surface.
 
@@ -6274,7 +6393,7 @@ that they hold, which is why a caller that needs the stronger fact has to
 check the laws at values rather than read this tuple.
 ### `tiergraph.schema`
 
-This module is importable and usable, but carries no API-stability promise at version 0.2.2.
+This module is importable and usable, but carries no API-stability promise at version 0.2.3.
 
 ### `Refusal`
 
@@ -6389,7 +6508,7 @@ shape_hash() -> 'str'
 Hash the declaration independently of JSON Schema presentation.
 ### `tiergraph.cli`
 
-This module is importable and usable, but carries no API-stability promise at version 0.2.2.
+This module is importable and usable, but carries no API-stability promise at version 0.2.3.
 
 ### `build_parser`
 
@@ -6408,7 +6527,7 @@ main(argv: 'Sequence[str] | None' = None) -> 'int'
 Run the command line. Returns the process exit status.
 ### `tiergraph.spanview`
 
-This module is importable and usable, but carries no API-stability promise at version 0.2.2.
+This module is importable and usable, but carries no API-stability promise at version 0.2.3.
 
 ### `SPANVIEW_FORMAT_VERSION`
 
@@ -6526,7 +6645,7 @@ to_text(view: 'SpanView', *, alternatives: 'bool' = False) -> 'str'
 Return a deterministic ruler and aligned plain-text span table.
 ### `tiergraph.textgrid`
 
-This module is importable and usable, but carries no API-stability promise at version 0.2.2.
+This module is importable and usable, but carries no API-stability promise at version 0.2.3.
 
 ### `TextGridReadResult`
 

{tiergraph-0.2.2 → tiergraph-0.2.3}/docs/reference/cli.md

@@ -2,7 +2,7 @@
 
 The `tiergraph` command prints help when called without arguments. `--version` prints one JSON object and exits successfully.
 
-`tiergraph.cli.build_parser()` is importable and usable, but carries no API-stability promise at version 0.2.2.
+`tiergraph.cli.build_parser()` is importable and usable, but carries no API-stability promise at version 0.2.3.
 
 ## Contracts
 

{tiergraph-0.2.2 → tiergraph-0.2.3}/src/tiergraph/__init__.py

@@ -1,5 +1,8 @@
 """tiergraph: ordered tiers, declared relations, and typed values."""
 
+import importlib
+from typing import TYPE_CHECKING, cast
+
 from tiergraph.action import (
     ActionDeclaration,
     DistributionWitness,
@@ -138,6 +141,14 @@ from tiergraph.path import (
     resolve_path,
 )
 from tiergraph.pathplan import AlgebraOrder, PathMarginals, PathPlan, PathPosteriors
+
+if TYPE_CHECKING:
+    from tiergraph.pathoutput import (
+        Emissions,
+        OutputItemMarginals,
+        OutputMasses,
+        OutputPlan,
+    )
 from tiergraph.profile import (
     PROFILES,
     GraphProfile,
@@ -220,7 +231,20 @@ from tiergraph.wire import (
     to_data,
 )
 
-__version__ = "0.2.2"
+__version__ = "0.2.3"
+
+_PATHOUTPUT_EXPORTS = frozenset(
+    {"Emissions", "OutputItemMarginals", "OutputMasses", "OutputPlan"}
+)
+
+
+def __getattr__(name: str) -> object:
+    """Load path-output composition only when its public names are requested."""
+    if name in _PATHOUTPUT_EXPORTS:
+        pathoutput = importlib.import_module("tiergraph.pathoutput")
+        return cast(object, getattr(pathoutput, name))
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
 
 __all__ = [
     "ARCTIC",
@@ -280,6 +304,7 @@ __all__ = [
     "DurablePolyadicRef",
     "DurableRelationRef",
     "EffectRefusal",
+    "Emissions",
     "ExactnessRefusal",
     "ExecutionError",
     "FoldCertificate",
@@ -323,6 +348,9 @@ __all__ = [
     "OrderedPolyadicTraversal",
     "OrderedRootsProfile",
     "OrphanedSubject",
+    "OutputItemMarginals",
+    "OutputMasses",
+    "OutputPlan",
     "ParseForest",
     "PathBinding",
     "PathKind",