span-contract 1.0.1__py3-none-any.whl

span_contract-1.0.1.dist-info/METADATA

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: span-contract
+Version: 1.0.1
+Summary: An admission contract for AI training jobs that cross a data hall boundary
+Author: Margaret Nanyonga
+License: MIT
+Project-URL: Homepage, https://github.com/dimaggi-ai/span-contract
+Project-URL: Research, https://dimaggi-ai.github.io/research
+Keywords: distributed training,admission control,data center interconnect,optical circuit switching,capacity planning
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: System :: Distributed Computing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest==8.3.4; extra == "dev"
+Dynamic: license-file
+
+# The span contract: deciding whether an AI training job may cross a data hall
+
+**When a job asks to run across more than one hall, who decides, and on what facts?**
+
+Today, three systems decide, and none of them talks to the others. The scheduler
+knows how many accelerators are free. The compiler knows what plan it emitted and
+what topology it assumed. The circuit controller knows what glass is lit. Each
+holds a different half-truth, and the job discovers which one was wrong at step
+time — or worse, at checkpoint time, three hours in.
+
+This repository is one object that makes them agree before the job starts:
+twenty-one fields, six decisions, three conditions under which the contract
+refuses rather than guesses, and a reference validator that turns the first into
+the second and prints its reasons. It is a research artifact, not a product.
+
+---
+
+## What it is not
+
+It is not a fabric, a scheduler, or a network model. It decides **admission** —
+may this job cross — and holds no opinion on **capacity** — what the job would
+retain if it did. That second question is answered by the latency-regime atlas in
+[network-vs-more-gpus](https://github.com/dimaggi-ai/network-vs-more-gpus), and
+this repository deliberately does not offer a second answer to it. The two are
+designed to be read together: the atlas says a tensor-parallel cut retains 0.004
+across any stitch at any distance, and the contract is what refuses to launch it.
+
+## The shape of it
+
+```python
+from spancontract import SpanEnvelope, validate
+
+verdict = validate(envelope)
+verdict.decision      # Decision.DENY
+verdict.reasons()     # ['[FC2] path measurement is 7200s old, past the 300s TTL']
+verdict.not_checked   # what the validator could not check, printed rather than omitted
+```
+
+```
+$ spancontract validate examples/long-haul-training-too-far.json
+decision: DENY
+regime:   region (2958 us RTT)
+
+findings:
+  - [LR1] synchronous train at 2958 us RTT (region) exceeds the 2000 us limit;
+          the default policy is that training stays hall-local
+
+not checked:
+  ? XP1 declared-vs-computed blast radius: no plant graph supplied, so the
+    envelope's blast_radius was taken on trust
+  ? XP2 topology currency: no live topology hash supplied, so the envelope's
+    topology_hash was taken on trust
+```
+
+## The three conditions that fail closed
+
+Each describes a state in which the contract *does not know* something it needs,
+and in each case not knowing is a refusal. A validator that read silence as
+health would be worse than no validator, because it would be trusted.
+
+| | Condition | Why it is a refusal and not a warning |
+|---|---|---|
+| **FC1** | The circuit API is dark | The state of the stitch is unknown. Unknown is not healthy. |
+| **FC2** | The measured path is stale past its TTL | A declared topology is a claim. Only a fresh measurement is an observation. |
+| **FC3** | The compile cache was keyed on a topology that no longer exists | The binary was built for a placement that is gone. |
+
+## The six decisions
+
+`local` · `span` · `shrink` · `move` · `escalate` · `deny`, on a severity ladder.
+Rules join with a maximum, so a rule can only push a verdict toward refusal and
+never away from it — which is what makes the order the rules run in irrelevant to
+the answer. The registry proves that by shuffling the rule list over 400 random
+envelopes and requiring every verdict to be identical.
+
+## What the validator refuses to pretend
+
+`make validate` prints the registry, and then prints the list of what it
+**declined** to check. That second list is the more useful one. It says, among
+other things, that no published figure fixes any threshold in this repository,
+that no verdict here has been checked against a job that actually ran, and that
+the emulated circuit models amplifier gain without the optical signal-to-noise
+cost that comes with it, so it can demonstrate a refusal but cannot support a
+claim of health.
+
+There is exactly **one calibrated point** in the registry. That is the honest
+count, not a gap. See [`docs/the-contract.md`](docs/the-contract.md).
+
+## Install and run
+
+```bash
+git clone https://github.com/dimaggi-ai/span-contract
+cd span-contract
+make venv
+make smoke-test      # tests, mutation tests, registry, examples — under a minute
+```
+
+Or from PyPI:
+
+```bash
+pip install span-contract
+spancontract example > envelope.json
+spancontract validate envelope.json
+```
+
+| Target | What it does |
+|---|---|
+| `make test` | 91 tests, including 12 mutation tests that delete machinery and require the registry to go red |
+| `make validate` | the validation registry, and the nine things it declines to check |
+| `make examples` | eleven example envelopes, each checked against its documented verdict |
+| `make schema` | regenerate `schema/span_contract.schema.json` from the code |
+
+## Repository map
+
+| Path | What is in it |
+|---|---|
+| `src/spancontract/envelope.py` | the twenty-one fields, inert by design |
+| `src/spancontract/rules.py` | every rule and every threshold, none of them inline |
+| `src/spancontract/validator.py` | the join, the plant cross-checks, the hash-chained record |
+| `src/spancontract/plant.py` | halls, circuits, and what one failure actually costs |
+| `src/spancontract/compile_cache.py` | keyed as specified; refuses entries from a dead topology |
+| `src/spancontract/adapters/delay_node.py` | an emulated circuit, and the `tc` line that reproduces it |
+| `validation/validate_contract.py` | the registry: one calibrated, seven emergent, ten sanity, nine declined |
+| `tests/test_mutations.py` | delete a piece, name the points that must go red |
+| `docs/the-contract.md` | the specification as implemented, including where it contradicts itself |
+| `docs/integration.md` | the surface an existing policy engine would bind to |
+
+## The discrepancy that was carried rather than fixed
+
+The specification lists six decisions, and then enumerates only five of them in
+the `span_mode` field: `escalate` is missing. Both are implemented exactly as
+written — a verdict can be `escalate`, and `span_mode` cannot — and a registry
+point asserts the gap is still there, so that quietly closing it in a future
+commit shows up as a failing check rather than a tidy-up. `DECISIONS.md` D3 has
+the reasoning.
+
+## Series
+
+Part of a program on the usable capacity of large accelerator fleets:
+[dimaggi-ai.github.io/research](https://dimaggi-ai.github.io/research).
+
+## License
+
+MIT. Copyright (c) 2026 Margaret Nanyonga.

span_contract-1.0.1.dist-info/RECORD

@@ -0,0 +1,17 @@
+span_contract-1.0.1.dist-info/licenses/LICENSE,sha256=N4CCXmxOGsKwf89eonmduSSy6i2ZX4mR7LxgmVfeal0,1074
+spancontract/__init__.py,sha256=S_u-bvenYw1EJ8GC0xpUqspEtCVD7pxzTqtOxVrFzK8,2040
+spancontract/cli.py,sha256=hVs0_Yu92xEQHR6LmUVxu1q3RssA-Zfx08FbzDzMavk,6191
+spancontract/compile_cache.py,sha256=KHbKlbXZLACgiHr2y9eXLduNK8YvvXg_eGk-RzjPAXI,4107
+spancontract/decisions.py,sha256=uFEkZi45z_1k-1CDQXpKd7Pjl3HHTndsQpLy7xFdgnw,2939
+spancontract/envelope.py,sha256=ZYg6HqcA0MVKkWv039GnjzxK9JghDJLhRKIwy0kXihI,9385
+spancontract/plant.py,sha256=oFRM5Do6zpD7qgKlV_Pl46qr-AQ0cb87mlmkZZR9Rc8,5674
+spancontract/rules.py,sha256=8PbS3a6Qv8Hl8zXMq4k1k_C7w0DF9PU-n8BSV8fIMFU,15054
+spancontract/schema.py,sha256=6K5HhxepYU0aOZs9zreFU-xUmQxosVVh6KuQgZMxPVE,5175
+spancontract/validator.py,sha256=812kcT2s2GYaiulKJ3w07Hh1896XV5_eaGR9fe0NTYw,8188
+spancontract/adapters/__init__.py,sha256=xQtzsVZ-TuNKwBvHVIl3kGJ9l325FGaqI9aMKP6FeCs,975
+spancontract/adapters/delay_node.py,sha256=ETwHE7vd8DKn9zv4Bq1nNdbZe2pzgveNOMneCfhd_6A,9175
+span_contract-1.0.1.dist-info/METADATA,sha256=MLx90R8rof_IyUk-ozn9b9-cZbU4UzbQvEeheYJnx1A,7380
+span_contract-1.0.1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+span_contract-1.0.1.dist-info/entry_points.txt,sha256=zKUYVWZ5I4HaFTYnknRDQSQmVN_K_sUU2b8MzqJT2Y8,55
+span_contract-1.0.1.dist-info/top_level.txt,sha256=qkE8yOiiiBTBGWZDNG7tLdWtH_Exv90cshl8Yu5oc2o,13
+span_contract-1.0.1.dist-info/RECORD,,

span_contract-1.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

span_contract-1.0.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+spancontract = spancontract.cli:main

span_contract-1.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Margaret Nanyonga
+
+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.

span_contract-1.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+spancontract

spancontract/__init__.py

@@ -0,0 +1,64 @@
+"""span-contract: one object a job carries when it wants to cross a hall.
+
+A scale-across decision is made today by three systems that do not talk: a
+scheduler that knows how many accelerators are free, a compiler that knows what
+plan it emitted, and a circuit controller that knows what glass is lit. Each
+holds a different half-truth about the topology, and the job finds out which
+one was wrong at step time.
+
+This package is the object that makes them agree before the job starts: a
+twenty-one field envelope, six decisions, three conditions that fail closed,
+and a reference validator that turns the first into the second and prints the
+reasons. It decides admission. It does not decide capacity --- what a job
+retains across a given cut is answered by the latency-regime atlas in the
+``network-vs-more-gpus`` repository, and this package deliberately holds no
+second opinion on it.
+
+    >>> from spancontract import SpanEnvelope, validate
+    >>> verdict = validate(envelope)   # doctest: +SKIP
+    >>> verdict.decision, verdict.reasons()   # doctest: +SKIP
+"""
+
+from .plant import SpanGraph, Stitch, blast_radius, load_bearing_stitches
+from .compile_cache import CompileCache, compile_cache_key
+from .decisions import SPAN_MODES, Decision, ScaleOut
+from .envelope import (
+    AUTONOMY_LEVELS,
+    REGIME_BOUNDS,
+    SPEC_FIELDS,
+    SliceRect,
+    SpanEnvelope,
+    latency_regime,
+)
+from .rules import FAIL_CLOSED_RULE_IDS, RULES, Finding, Policy
+from .validator import Plant, Verdict, audit_record, validate, verify_chain
+
+__version__ = "1.0.1"
+
+__all__ = [
+    "AUTONOMY_LEVELS",
+    "CompileCache",
+    "Decision",
+    "FAIL_CLOSED_RULE_IDS",
+    "Finding",
+    "Plant",
+    "Policy",
+    "REGIME_BOUNDS",
+    "RULES",
+    "SPAN_MODES",
+    "SPEC_FIELDS",
+    "ScaleOut",
+    "SliceRect",
+    "SpanEnvelope",
+    "SpanGraph",
+    "Stitch",
+    "Verdict",
+    "audit_record",
+    "blast_radius",
+    "compile_cache_key",
+    "latency_regime",
+    "load_bearing_stitches",
+    "validate",
+    "verify_chain",
+    "__version__",
+]

spancontract/adapters/__init__.py

@@ -0,0 +1,29 @@
+"""Adapters between the contract and something that can answer for a circuit.
+
+The contract needs one thing from the outside world: a measurement of the path,
+with an age and an honest "I could not reach the controller". That is the whole
+:class:`StitchController` surface. Everything else in this repository works off
+the envelope.
+
+Two adapters ship here. :mod:`spancontract.adapters.delay_node` is an emulated
+circuit, which is what section 9's seventh sequence item asks for and what a
+reader can run today. A real controller --- a lab OCS, a campus ROADM --- binds
+to the same protocol; this repository does not ship one, because writing a
+driver against a plant nobody has run it on would be fiction.
+"""
+
+from .delay_node import (
+    DelayNode,
+    EmulatedController,
+    PathMeasurement,
+    StitchController,
+    apply_measurement,
+)
+
+__all__ = [
+    "DelayNode",
+    "EmulatedController",
+    "PathMeasurement",
+    "StitchController",
+    "apply_measurement",
+]

spancontract/adapters/delay_node.py

@@ -0,0 +1,217 @@
+"""An emulated stitch: a delay node standing in for a circuit.
+
+Section 9's seventh sequence item is to prove the contract against an emulated
+delay node before anyone points it at glass. This module is that node. It
+answers probes the way a circuit controller would, with a round-trip time, an
+insertion loss, an error rate, and --- the part that matters --- the ability to
+be *dark*, so the fail-closed path is exercised by something other than a unit
+test constructing the failure by hand.
+
+What this is not: a network simulator. It does not model queueing, congestion,
+or the interaction between a collective and a checkpoint on one circuit. It
+returns the numbers a controller would return so that the contract's plumbing
+can be exercised end to end. The capacity question --- what a job actually
+retains across a given cut --- is answered by the model in the
+``network-vs-more-gpus`` repository, not here, and this module deliberately
+does not offer a second opinion on it.
+
+One limit is worth stating before anyone reads a green result as an
+engineering answer. Amplification is modelled as gain and nothing else. Real
+amplifiers cost optical signal-to-noise ratio, and OSNR is what actually sets
+the error rate on a long span, so an amplified path here reports a comfortable
+insertion loss and a bit error rate the caller made up. The emulator can show
+that the contract *refuses* an unhealthy circuit; it cannot be used to argue a
+particular circuit is healthy. ASSUMPTIONS.md A4 records this.
+
+To run the same shape against real kernels rather than this object,
+:func:`DelayNode.netem_command` prints the ``tc`` line that reproduces its
+delay and loss on a Linux box between two halls. That is the bridge from this
+file to a lab, and it is one command long.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass, replace
+from typing import Optional, Protocol, runtime_checkable
+
+from ..envelope import SpanEnvelope, latency_regime
+
+#: Speed of light in single-mode fibre, metres per second. Group index ~1.4682.
+FIBRE_C_M_PER_S = 299_792_458.0 / 1.4682
+#: Loss of a typical single-mode span at 1550 nm, dB per km. A planning figure,
+#: not a measurement of any particular cable: real plant runs higher once
+#: splices and connectors are counted, which is why the emulator lets a caller
+#: add a fixed penalty rather than pretending this is the whole loss.
+FIBRE_LOSS_DB_PER_KM = 0.20
+
+
+@dataclass(frozen=True)
+class PathMeasurement:
+    """What a controller returns when asked about a circuit.
+
+    ``reachable=False`` is a real answer and a different thing from an
+    exception: the probe completed and the controller is dark. ``None`` for the
+    numbers in that case, because a dark controller reports nothing, and
+    carrying a stale number forward as if it were fresh is the failure this
+    whole contract exists to prevent.
+    """
+
+    stitch_id: str
+    reachable: bool
+    rtt_us: Optional[float] = None
+    insertion_loss_db: Optional[float] = None
+    bit_error_rate: Optional[float] = None
+    bandwidth_gbps: Optional[float] = None
+    age_s: float = 0.0
+
+    @property
+    def regime(self) -> Optional[str]:
+        return None if self.rtt_us is None else latency_regime(self.rtt_us)
+
+
+@runtime_checkable
+class StitchController(Protocol):
+    """The one thing the contract needs from a circuit controller."""
+
+    def probe(self, stitch_id: str) -> PathMeasurement:
+        """Return the current state of the path, or a dark answer."""
+        ...
+
+
+@dataclass(frozen=True)
+class DelayNode:
+    """An emulated circuit between two halls.
+
+    Round-trip time is derived from the fibre length rather than set directly,
+    so a caller changing the distance cannot forget to change the latency --- a
+    mistake that makes an emulator agree with whatever it is testing.
+    """
+
+    stitch_id: str
+    distance_km: float
+    bandwidth_gbps: float = 800.0
+    #: Loss beyond the fibre itself: splices, patch panels, an OCS crossbar.
+    excess_loss_db: float = 2.0
+    #: Total amplifier gain on the path, in dB. Zero models an unamplified
+    #: span, which is why a long one here trips the loss budget: at 0.2 dB/km a
+    #: 120 km hop arrives 26 dB down, and a real one would carry amplifiers.
+    #: Set this to model an amplified path --- but see the class docstring for
+    #: what that does *not* buy you.
+    amplifier_gain_db: float = 0.0
+    bit_error_rate: float = 1e-12
+    #: Extra one-way latency from transponders and any regeneration, in
+    #: microseconds. Real metro paths are not pure glass.
+    equipment_latency_us: float = 10.0
+    #: Set to False to emulate a dark controller.
+    reachable: bool = True
+    #: How stale the controller's own last measurement is.
+    age_s: float = 0.0
+
+    def __post_init__(self) -> None:
+        if self.distance_km < 0:
+            raise ValueError("distance_km must be non-negative")
+        if self.bandwidth_gbps <= 0:
+            raise ValueError("bandwidth_gbps must be positive")
+        if not 0.0 <= self.bit_error_rate <= 1.0:
+            raise ValueError("bit_error_rate must be a probability in [0, 1]")
+        if self.amplifier_gain_db < 0:
+            raise ValueError("amplifier_gain_db must be non-negative")
+
+    @property
+    def rtt_us(self) -> float:
+        """Round trip: two passes through the glass, plus the equipment."""
+        one_way_s = (self.distance_km * 1_000.0) / FIBRE_C_M_PER_S
+        return 2.0 * (one_way_s * 1e6 + self.equipment_latency_us)
+
+    @property
+    def insertion_loss_db(self) -> float:
+        loss = self.distance_km * FIBRE_LOSS_DB_PER_KM + self.excess_loss_db
+        return max(0.0, loss - self.amplifier_gain_db)
+
+    def go_dark(self) -> "DelayNode":
+        """The same node with its controller unreachable."""
+        return replace(self, reachable=False)
+
+    def aged(self, seconds: float) -> "DelayNode":
+        """The same node whose last measurement is ``seconds`` old."""
+        return replace(self, age_s=seconds)
+
+    def measure(self) -> PathMeasurement:
+        if not self.reachable:
+            return PathMeasurement(self.stitch_id, reachable=False, age_s=self.age_s)
+        return PathMeasurement(
+            stitch_id=self.stitch_id,
+            reachable=True,
+            rtt_us=self.rtt_us,
+            insertion_loss_db=self.insertion_loss_db,
+            bit_error_rate=self.bit_error_rate,
+            bandwidth_gbps=self.bandwidth_gbps,
+            age_s=self.age_s,
+        )
+
+    def netem_command(self, interface: str = "eth0") -> str:
+        """The ``tc`` line reproducing this node's delay on a Linux box.
+
+        Emitted rather than executed. Running it needs root on a machine
+        between two halls, which is a decision for whoever owns that machine.
+        Loss is expressed as a percentage, so a bit error rate below 1e-8
+        rounds to zero here --- netem cannot express it, and the command says
+        so instead of silently dropping the term.
+        """
+        one_way_ms = self.rtt_us / 2_000.0
+        loss_pct = self.bit_error_rate * 100.0
+        parts = [
+            f"tc qdisc replace dev {interface} root netem",
+            f"delay {one_way_ms:.3f}ms",
+            f"rate {self.bandwidth_gbps:.0f}gbit",
+        ]
+        if loss_pct >= 1e-6:
+            parts.append(f"loss {loss_pct:.6f}%")
+        else:
+            parts.append(f"# loss {loss_pct:.3e}% below netem resolution, omitted")
+        return " ".join(parts)
+
+
+@dataclass(frozen=True)
+class EmulatedController:
+    """A :class:`StitchController` over a set of delay nodes."""
+
+    nodes: tuple
+
+    def node(self, stitch_id: str) -> DelayNode:
+        for n in self.nodes:
+            if n.stitch_id == stitch_id:
+                return n
+        raise KeyError(f"no emulated stitch {stitch_id!r}")
+
+    def probe(self, stitch_id: str) -> PathMeasurement:
+        return self.node(stitch_id).measure()
+
+
+def apply_measurement(env: SpanEnvelope, m: PathMeasurement) -> SpanEnvelope:
+    """Fill an envelope's measured fields from a probe.
+
+    A dark probe leaves the declared numbers untouched and sets
+    ``stitch_api_reachable`` to False. It does *not* zero them or invent
+    pessimistic ones: the envelope should record what was declared and,
+    separately, that nobody could confirm it. Rule FC1 turns that into a
+    refusal, which keeps the reason for the refusal legible in the audit
+    record instead of hidden behind a substituted value.
+    """
+    if m.stitch_id != env.stitch_id:
+        raise ValueError(
+            f"measurement is for stitch {m.stitch_id!r}, envelope names {env.stitch_id!r}"
+        )
+    if not m.reachable:
+        return env.replace(stitch_api_reachable=False, measured_age_s=m.age_s)
+    changes = {"stitch_api_reachable": True, "measured_age_s": m.age_s}
+    if m.rtt_us is not None:
+        changes["span_rtt_us"] = m.rtt_us
+    if m.insertion_loss_db is not None:
+        changes["measured_il_db"] = m.insertion_loss_db
+    if m.bit_error_rate is not None:
+        changes["measured_ber"] = m.bit_error_rate
+    if m.bandwidth_gbps is not None:
+        changes["span_bw_gbps"] = m.bandwidth_gbps
+    return env.replace(**changes)