fleetmesh-core 0.2.0__tar.gz

fleetmesh_core-0.2.0/LICENSE

@@ -0,0 +1,121 @@
+Creative Commons Legal Code
+
+CC0 1.0 Universal
+
+    CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE
+    LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN
+    ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS
+    INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES
+    REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS
+    PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM
+    THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED
+    HEREUNDER.
+
+Statement of Purpose
+
+The laws of most jurisdictions throughout the world automatically confer
+exclusive Copyright and Related Rights (defined below) upon the creator
+and subsequent owner(s) (each and all, an "owner") of an original work of
+authorship and/or a database (each, a "Work").
+
+Certain owners wish to permanently relinquish those rights to a Work for
+the purpose of contributing to a commons of creative, cultural and
+scientific works ("Commons") that the public can reliably and without fear
+of later claims of infringement build upon, modify, incorporate in other
+works, reuse and redistribute as freely as possible in any form whatsoever
+and for any purposes, including without limitation commercial purposes.
+These owners may contribute to the Commons to promote the ideal of a free
+culture and the further production of creative, cultural and scientific
+works, or to gain reputation or greater distribution for their Work in
+part through the use and efforts of others.
+
+For these and/or other purposes and motivations, and without any
+expectation of additional consideration or compensation, the person
+associating CC0 with a Work (the "Affirmer"), to the extent that he or she
+is an owner of Copyright and Related Rights in the Work, voluntarily
+elects to apply CC0 to the Work and publicly distribute the Work under its
+terms, with knowledge of his or her Copyright and Related Rights in the
+Work and the meaning and intended legal effect of CC0 on those rights.
+
+1. Copyright and Related Rights. A Work made available under CC0 may be
+protected by copyright and related or neighboring rights ("Copyright and
+Related Rights"). Copyright and Related Rights include, but are not
+limited to, the following:
+
+  i. the right to reproduce, adapt, distribute, perform, display,
+     communicate, and translate a Work;
+ ii. moral rights retained by the original author(s) and/or performer(s);
+iii. publicity and privacy rights pertaining to a person's image or
+     likeness depicted in a Work;
+ iv. rights protecting against unfair competition in regards to a Work,
+     subject to the limitations in paragraph 4(a), below;
+  v. rights protecting the extraction, dissemination, use and reuse of data
+     in a Work;
+ vi. database rights (such as those arising under Directive 96/9/EC of the
+     European Parliament and of the Council of 11 March 1996 on the legal
+     protection of databases, and under any national implementation
+     thereof, including any amended or successor version of such
+     directive); and
+vii. other similar, equivalent or corresponding rights throughout the
+     world based on applicable law or treaty, and any national
+     implementations thereof.
+
+2. Waiver. To the greatest extent permitted by, but not in contravention
+of, applicable law, Affirmer hereby overtly, fully, permanently,
+irrevocably and unconditionally waives, abandons, and surrenders all of
+Affirmer's Copyright and Related Rights and associated claims and causes
+of action, whether now known or unknown (including existing as well as
+future claims and causes of action), in the Work (i) in all territories
+worldwide, (ii) for the maximum duration provided by applicable law or
+treaty (including future time extensions), (iii) in any current or future
+medium and for any number of copies, and (iv) for any purpose whatsoever,
+including without limitation commercial, advertising or promotional
+purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each
+member of the public at large and to the detriment of Affirmer's heirs and
+successors, fully intending that such Waiver shall not be subject to
+revocation, rescission, cancellation, termination, or any other legal or
+equitable action to disrupt the quiet enjoyment of the Work by the public
+as contemplated by Affirmer's express Statement of Purpose.
+
+3. Public License Fallback. Should any part of the Waiver for any reason
+be judged legally invalid or ineffective under applicable law, then the
+Waiver shall be preserved to the maximum extent permitted taking into
+account Affirmer's express Statement of Purpose. In addition, to the
+extent the Waiver is so judged Affirmer hereby grants to each affected
+person a royalty-free, non transferable, non sublicensable, non exclusive,
+irrevocable and unconditional license to exercise Affirmer's Copyright and
+Related Rights in the Work (i) in all territories worldwide, (ii) for the
+maximum duration provided by applicable law or treaty (including future
+time extensions), (iii) in any current or future medium and for any number
+of copies, and (iv) for any purpose whatsoever, including without
+limitation commercial, advertising or promotional purposes (the
+"License"). The License shall be deemed effective as of the date CC0 was
+applied by Affirmer to the Work. Should any part of the License for any
+reason be judged legally invalid or ineffective under applicable law, such
+partial invalidity or ineffectiveness shall not invalidate the remainder
+of the License, and in such case Affirmer hereby affirms that he or she
+will not (i) exercise any of his or her remaining Copyright and Related
+Rights in the Work or (ii) assert any associated claims and causes of
+action with respect to the Work, in either case contrary to Affirmer's
+express Statement of Purpose.
+
+4. Limitations and Disclaimers.
+
+ a. No trademark or patent rights held by Affirmer are waived, abandoned,
+    surrendered, licensed or otherwise affected by this document.
+ b. Affirmer offers the Work as-is and makes no representations or
+    warranties of any kind concerning the Work, express, implied,
+    statutory or otherwise, including without limitation warranties of
+    title, merchantability, fitness for a particular purpose, non
+    infringement, or the absence of latent or other defects, accuracy, or
+    the present or absence of errors, whether or not discoverable, all to
+    the greatest extent permissible under applicable law.
+ c. Affirmer disclaims responsibility for clearing rights of other persons
+    that may apply to the Work or any use thereof, including without
+    limitation any person's Copyright and Related Rights in the Work.
+    Further, Affirmer disclaims responsibility for obtaining any necessary
+    consents, permissions or other rights required for any use of the
+    Work.
+ d. Affirmer understands and acknowledges that Creative Commons is not a
+    party to this document and has no duty or obligation with respect to
+    this CC0 or use of the Work.

fleetmesh_core-0.2.0/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: fleetmesh-core
+Version: 0.2.0
+Summary: Core protocols, typed contracts, and wire primitives for Fleetmesh
+License: CC0-1.0
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fleetmesh-schema>=0.1.0
+Provides-Extra: postgres
+Requires-Dist: psycopg[binary]==3.3.6; extra == "postgres"
+Provides-Extra: crypto
+Requires-Dist: cryptography>=42; extra == "crypto"
+Dynamic: license-file
+
+# Fleetmesh Core
+
+Core protocol primitives, typed contracts, Negentropy reconciliation, and signed budget accounting for **Fleetmesh** ([fleetmesh.org](https://www.fleetmesh.org)).
+
+## Domain Subpackages
+
+`fleetmesh_core` is standard-library-only Python (zero external dependencies, no I/O, no wall clock) organized into eight domain subpackages:
+
+- **`fleetmesh_core.crypto`**:
+  - `crypto.py`, `keys.py`, `curve.py`, `bech32.py`: BIP-340 Schnorr, X25519 ECDH, Ed25519, Multikey (`z6Mk...`), HKDF-SHA256, ChaCha20-Poly1305.
+  - `nip44.py`, `giftwrap.py`: NIP-44 v2 padded encryption and NIP-59 gift-wrapping (kinds 1059 / 21059).
+  - `zk.py`: BN254 pairing and Groth16 verification for `compute:zk-verify-groth16/1.0` (`vectors/groth16.json`).
+  - `http_signatures.py`: RFC 9421 HTTP Message Signatures and Digest headers for ActivityPub federation.
+  - `ssb.py`: Secure Scuttlebutt Secret Handshake (SHS), Box Stream framing, and V1 feed verification.
+- **`fleetmesh_core.identity`**:
+  - `identity.py`, `did.py`, `origin.py`, `relaylist.py`: Descriptor validation, PoW, blinded tags, `did:nostr`, `did:key`, `did:peer:2`, and NIP-65 relay lists.
+  - `atproto.py`: ATProto `did:plc` genesis operation signing, `did:web` resolution, and K-256 ECDSA verification.
+  - `didcomm.py`: DIDComm v2 ECDH-1PU / ECDH-ES envelope packing.
+  - `cid.py`, `iroh_ticket.py`: CIDv1 (`bafkrei...`) content addressing and Iroh `NodeTicket` serialization.
+- **`fleetmesh_core.peering`**:
+  - `peering.py`, `coverage.py`, `projection.py`: Bilateral `peering/1.0` state machine, Kind 30803 coverage claims and handovers, and NIP-85 Kind 30385 projections.
+  - `complaint.py`, `reports.py`, `release.py`, `badpeer.py`: `complaint/1.0` notices, Kind 30802 admissibility, Kind 9900/9901 signed releases, and synthetic adversarial peer.
+- **`fleetmesh_core.accounting`**:
+  - `accounting.py`, `window.py`, `capacity.py`, `strain.py`, `standing.py`: Monotonic receipt chains, AIMD window evaluation, capacity shedding, directional strain, and `standing/1.0`.
+  - `cashu.py`, `paidfetch.py`, `market.py`: Cashu BDHKE (NUT-00..24), HTTP 402 PaidFetch quotes, and compute market commitments.
+- **`fleetmesh_core.storage`**:
+  - `store.py`, `store_postgres.py`: SQLite and PostgreSQL event store and range indexing.
+  - `negentropy.py`, `sync.py`, `replication.py`: NIP-77 V1 range-based set reconciliation, delivery envelopes, and blob replication.
+  - `blossom_auth.py`, `linked_data.py`: Blossom BUD-01/04 authorization and JSON-LD / Schema.org projections.
+  - `car.py`, `mst.py`: Content Addressable aRchives (CAR v1) and ATProto Merkle Search Trees (MST).
+- **`fleetmesh_core.services`**:
+  - `compute.py`, `dvm.py`, `gossip.py`, `mediation.py`, `nsite.py`, `nwc.py`, `settlement.py`, `sidecar.py`, `ucan.py`.
+- **`fleetmesh_core.wire`**:
+  - `interfaces.py`, `wire_types.py`, `validate.py`, `schema_files.py`: Typed contracts, strict wire parsers, and cached schema loaders.
+  - `cbor.py`, `p2panda.py`: Canonical DAG-CBOR (with Tag 42 CID links) and p2panda Ed25519 + CBOR append-only operation logs.
+- **`fleetmesh_core.conformance`**:
+  - `runner.py`: Clean-room JSON-lines conformance harness responder (`python3 -m fleetmesh_core.conformance`).
+
+## Installation
+
+```sh
+pip install -e .
+```
+
+## Running Tests
+
+```sh
+PYTHONPATH=. python3 tests/test_discovery.py
+PYTHONPATH=. python3 tests/test_negentropy.py
+PYTHONPATH=. python3 tests/test_strain.py
+```
+
+## Licence
+
+[CC0 1.0 Universal](LICENSE)

fleetmesh_core-0.2.0/README.md

@@ -0,0 +1,55 @@
+# Fleetmesh Core
+
+Core protocol primitives, typed contracts, Negentropy reconciliation, and signed budget accounting for **Fleetmesh** ([fleetmesh.org](https://www.fleetmesh.org)).
+
+## Domain Subpackages
+
+`fleetmesh_core` is standard-library-only Python (zero external dependencies, no I/O, no wall clock) organized into eight domain subpackages:
+
+- **`fleetmesh_core.crypto`**:
+  - `crypto.py`, `keys.py`, `curve.py`, `bech32.py`: BIP-340 Schnorr, X25519 ECDH, Ed25519, Multikey (`z6Mk...`), HKDF-SHA256, ChaCha20-Poly1305.
+  - `nip44.py`, `giftwrap.py`: NIP-44 v2 padded encryption and NIP-59 gift-wrapping (kinds 1059 / 21059).
+  - `zk.py`: BN254 pairing and Groth16 verification for `compute:zk-verify-groth16/1.0` (`vectors/groth16.json`).
+  - `http_signatures.py`: RFC 9421 HTTP Message Signatures and Digest headers for ActivityPub federation.
+  - `ssb.py`: Secure Scuttlebutt Secret Handshake (SHS), Box Stream framing, and V1 feed verification.
+- **`fleetmesh_core.identity`**:
+  - `identity.py`, `did.py`, `origin.py`, `relaylist.py`: Descriptor validation, PoW, blinded tags, `did:nostr`, `did:key`, `did:peer:2`, and NIP-65 relay lists.
+  - `atproto.py`: ATProto `did:plc` genesis operation signing, `did:web` resolution, and K-256 ECDSA verification.
+  - `didcomm.py`: DIDComm v2 ECDH-1PU / ECDH-ES envelope packing.
+  - `cid.py`, `iroh_ticket.py`: CIDv1 (`bafkrei...`) content addressing and Iroh `NodeTicket` serialization.
+- **`fleetmesh_core.peering`**:
+  - `peering.py`, `coverage.py`, `projection.py`: Bilateral `peering/1.0` state machine, Kind 30803 coverage claims and handovers, and NIP-85 Kind 30385 projections.
+  - `complaint.py`, `reports.py`, `release.py`, `badpeer.py`: `complaint/1.0` notices, Kind 30802 admissibility, Kind 9900/9901 signed releases, and synthetic adversarial peer.
+- **`fleetmesh_core.accounting`**:
+  - `accounting.py`, `window.py`, `capacity.py`, `strain.py`, `standing.py`: Monotonic receipt chains, AIMD window evaluation, capacity shedding, directional strain, and `standing/1.0`.
+  - `cashu.py`, `paidfetch.py`, `market.py`: Cashu BDHKE (NUT-00..24), HTTP 402 PaidFetch quotes, and compute market commitments.
+- **`fleetmesh_core.storage`**:
+  - `store.py`, `store_postgres.py`: SQLite and PostgreSQL event store and range indexing.
+  - `negentropy.py`, `sync.py`, `replication.py`: NIP-77 V1 range-based set reconciliation, delivery envelopes, and blob replication.
+  - `blossom_auth.py`, `linked_data.py`: Blossom BUD-01/04 authorization and JSON-LD / Schema.org projections.
+  - `car.py`, `mst.py`: Content Addressable aRchives (CAR v1) and ATProto Merkle Search Trees (MST).
+- **`fleetmesh_core.services`**:
+  - `compute.py`, `dvm.py`, `gossip.py`, `mediation.py`, `nsite.py`, `nwc.py`, `settlement.py`, `sidecar.py`, `ucan.py`.
+- **`fleetmesh_core.wire`**:
+  - `interfaces.py`, `wire_types.py`, `validate.py`, `schema_files.py`: Typed contracts, strict wire parsers, and cached schema loaders.
+  - `cbor.py`, `p2panda.py`: Canonical DAG-CBOR (with Tag 42 CID links) and p2panda Ed25519 + CBOR append-only operation logs.
+- **`fleetmesh_core.conformance`**:
+  - `runner.py`: Clean-room JSON-lines conformance harness responder (`python3 -m fleetmesh_core.conformance`).
+
+## Installation
+
+```sh
+pip install -e .
+```
+
+## Running Tests
+
+```sh
+PYTHONPATH=. python3 tests/test_discovery.py
+PYTHONPATH=. python3 tests/test_negentropy.py
+PYTHONPATH=. python3 tests/test_strain.py
+```
+
+## Licence
+
+[CC0 1.0 Universal](LICENSE)

fleetmesh_core-0.2.0/fleetmesh_core/__init__.py

@@ -0,0 +1,10 @@
+"""fleetmesh executable reference implementation.
+
+Standard library only, no I/O, no clock, no network, and every constant read
+from schema/. Contains reference mechanisms for Nostr event storage,
+reconciliation, peering, accounting, capacity management, and reporting.
+"""
+from __future__ import annotations
+
+__version__ = '0.2.0'
+

fleetmesh_core-0.2.0/fleetmesh_core/accounting/__init__.py

@@ -0,0 +1,7 @@
+"""Accounting, capacity limits, settlement, Cashu, and strain."""
+from __future__ import annotations
+
+from . import accounting
+
+__all__ = ['accounting']
+

fleetmesh_core-0.2.0/fleetmesh_core/accounting/accounting.py

@@ -0,0 +1,215 @@
+"""Receipts, their hash chain, and telling a dead peer from a lying one.
+
+The chain is what stops a subject rewriting an earlier claim once it learns what
+the issuer measured. The issuer keeps the head, which is 32 bytes per window,
+and the most recent body, because that body is the claim the window is
+evaluated against and the evidence any report about it must carry.
+"""
+from __future__ import annotations
+
+import hashlib
+from typing import Any, Mapping, Optional, Sequence
+
+from ..crypto import crypto
+
+from ..wire import schema_files
+from ..wire.interfaces import ReceiptBody
+
+CONSTANTS = schema_files.load_constants()
+
+ZERO: str = '00' * 32
+
+
+def canonical(receipt: Mapping[str, Any]) -> bytes:
+    """constants.json canonical.form: keys sorted by code point, no whitespace -
+    crypto.canonical, with one difference:
+
+    `sig` is excluded, because it is a signature over this. Excluding it means
+    the chain link is the same value whether or not the receipt has been signed
+    yet, so signing changes no head and breaks no chain.
+    """
+    return crypto.canonical({k: v for k, v in receipt.items() if k != 'sig'})
+
+
+def link(receipt: Mapping[str, Any]) -> str:
+    return hashlib.sha256(canonical(receipt)).hexdigest()
+
+
+def sign_receipt(body: ReceiptBody, sk_hex: str) -> ReceiptBody:
+    """The subject signs its own claim. BIP-340 over the chain link, which is
+    already SHA-256 of the canonical body, so no second construction is defined
+    and the head the issuer acknowledges is the message that was signed.
+
+    This is what makes a receipt evidence. Without it a report about divergence
+    cites a number only the reporter has ever seen the subject state, which is
+    hearsay; with it the subject's half of the disagreement is pinned and the
+    reporter is trusted only for its own measurement.
+    """
+    signed: ReceiptBody = {**body, 'sig': crypto.schnorr_sign(bytes.fromhex(link(body)), sk_hex)}
+    return signed
+
+
+def verify_receipt(body: Mapping[str, Any], subject_pubkey: str) -> bool:
+    """True when this receipt carries the subject's signature over its own link."""
+    sig = body.get('sig')
+    if not sig:
+        return False
+    try:
+        return crypto.schnorr_verify(bytes.fromhex(link(body)), subject_pubkey, sig)
+    except (ValueError, TypeError):
+        return False
+
+
+def build_chain(grant_id: str, window: int, counter_series: Sequence[Mapping[str, int]], start_at: int = 1787000000, step: int = 600) -> Mapping[str, Any]:
+    """Produce a well-formed chain. Counters are cumulative and monotonic."""
+    chain = []
+    prev = ZERO
+    for seq, counters in enumerate(counter_series):
+        body = {'grant': grant_id, 'window': window, 'seq': seq, 'prev': prev,
+                                'counters': dict(counters), 'at': start_at + seq * step}
+        h = link(body)
+        chain.append({'receipt': body, 'canonical': canonical(body).decode(), 'sha256': h})
+        prev = h
+    return {'chain': chain, 'head': prev}
+
+
+def verify_chain(chain: Sequence[Mapping[str, Any]], head: Optional[str] = None) -> list[str]:
+    """Check every link, sequence number and monotonicity claim.
+
+    Returns a list of failures; empty means the chain holds. A subject that
+    rewrote seq 3 after the fact cannot also produce a matching seq 4.
+
+    This is strict about sequence, and stays strict, because what it checks is
+    a *complete* chain carried as evidence: a report cites what its subject
+    signed, and a chain with a hole in it is not the artefact it claims to be.
+    Live intake is the other case and is deliberately not this one -
+    `node.budget.on_receipt` tolerates a gap, because there the missing link is
+    the wire rather than the subject, and refusing it costs a whole window.
+    """
+    out: list[str] = []
+    prev = ZERO
+    last: Optional[Mapping[str, int]] = None
+    for i, entry in enumerate(chain):
+        r = entry['receipt']
+        if r.get('seq') != i:
+            out.append('link %d: seq is %s' % (i, r.get('seq')))
+        if r.get('prev') != prev:
+            out.append('link %d: prev does not chain' % i)
+        if entry.get('canonical') is not None and entry['canonical'] != canonical(r).decode():
+            out.append('link %d: canonical form does not match the body' % i)
+        h = link(r)
+        if entry.get('sha256') and entry['sha256'] != h:
+            out.append('link %d: stated hash is wrong' % i)
+        if last is not None:
+            for k, v in r.get('counters', {}).items():
+                if k in last and v < last[k]:
+                    out.append('link %d: counter %s went backwards' % (i, k))
+        last = r.get('counters', {})
+        prev = h
+    if head is not None and prev != head:
+        out.append('head does not match the final link')
+    return out
+
+
+def admissible_prefix(receipts: Sequence[Mapping[str, Any]]) -> tuple[list[Mapping[str, Any]], bool]:
+    """The longest gap-free, chain-verified prefix of a stored receipt list,
+    and whether anything was cut.
+
+    Live intake (`node.budget.on_receipt`) tolerates a lost link: a receipt
+    at seq 5 after seq 3 is stored, because the hole is the wire's and
+    refusing it costs a window. `verify_chain` is strict for the same reason
+    in the opposite direction: a chain cited as evidence must be the artefact
+    the subject signed, whole. Reporter used to attach every stored body, so
+    an S2 about a peer that lost one receipt on the wire carried a chain a
+    verifier would reject on sight - and a report with inadmissible evidence
+    is discarded unread. This keeps what verifies, from seq 0 up to the first
+    hole or broken link, so what is published is always admissible; partial
+    is reported so the caller can say so.
+    """
+    kept: list[Mapping[str, Any]] = []
+    prev = ZERO
+    last: Optional[Mapping[str, int]] = None
+    for i, r in enumerate(receipts):
+        if r.get('seq') != i or r.get('prev') != prev:
+            break
+        if last is not None and any(k in last and v < last[k] for k, v in r.get('counters', {}).items()):
+            break
+        kept.append(dict(r))
+        prev = link(r)
+        last = r.get('counters', {})
+    return kept, len(kept) != len(receipts)
+
+
+def silence(measured: Mapping[str, int]) -> Mapping[str, Any]:
+    """Active or inactive silence, per the partition-tolerance rule.
+
+    Receipts missing while the peer moved bytes is a misreport. Receipts missing
+    while it moved nothing is a partition, and FLP says you cannot tell a dead
+    node from a quiet one - so the protocol does not try, and prices only the
+    case where physical traffic contradicts the silence.
+    """
+    egress = sum(v for k, v in measured.items()
+                 if k in ('events_in', 'bytes_in', 'bytes_out', 'req', 'sync_ranges'))
+    if egress > 0:
+        return {'state': 'active-silence', 'severity': 'S2',
+                'remedy': 'limit x %s, tier to probation, report published'
+                          % CONSTANTS['grant']['aimd_decrease_s2']}
+    return {'state': 'inactive-silence', 'severity': None,
+            'remedy': 'not evaluated, streak neither advanced nor broken, no penalty, no report'}
+
+
+def window_claim(receipts: Sequence[Mapping[str, Any]], measured: Mapping[str, int]) -> tuple[str, Optional[dict[str, int]]]:
+    """What a window is evaluated against, per constants.json grant.window_evaluation.
+
+    receipts are the bodies received this window, in order. The most recent one
+    is the claim: counters are cumulative, so it already states the whole window,
+    and the chain makes it binding. A subject that sent receipts and then went
+    quiet is evaluated on what it last said against what was measured after -
+    which is how a leaf that syncs and then sleeps produces no finding, and a
+    peer that kept moving bytes after its last receipt is priced by divergence.
+    Returns (state, counters): ('claim', counters), ('active-silence', None) or
+    ('not-evaluated', None).
+
+    None means there is no claim, not that there is nothing to evaluate. A
+    window measured with no receipt is still evaluated - against the empty
+    claim, which is what vectors/window.json's "no receipt at all" case does -
+    and active silence is a *floor* of S2 on top of that. Skipping the
+    arithmetic would price a peer that overran and said nothing below the same
+    peer reporting it honestly, which is the inversion docs/mechanisms.md § 9
+    describes for divergence, in its other form.
+    """
+    if receipts:
+        return 'claim', dict(receipts[-1]['counters'])
+    return ('active-silence' if silence(measured)['severity'] else 'not-evaluated'), None
+
+
+def close_is_final(close_at: int, window_end: int, window_seconds: int) -> bool:
+    """A close arriving within the grace period is accepted as the window's final
+    receipt; later than that it is evaluated like any other receipt.
+
+    The grace span is half-open like the window itself: [window_end,
+    window_end + grace). The evaluator fires once `now >= window_end + grace`
+    (node budget/windows.py), so a close stamped at exactly that instant
+    arrives at or after evaluation and is late, not final."""
+    return close_at < window_end + window_grace(window_seconds)
+
+
+def epoch(unix_seconds: int, window_seconds: int) -> int:
+    """floor(t / window). Derived from the clock, so it cannot pause.
+
+    A dormant span advances the epoch counter and simply is not evaluated:
+    the streak neither advances nor breaks, and the next active window starts
+    a fresh chain at seq 0. The window is [epoch * window, (epoch+1) * window).
+    """
+    return unix_seconds // window_seconds
+
+
+def window_bounds(epoch_index: int, window_seconds: int) -> tuple[int, int]:
+    return (epoch_index * window_seconds, (epoch_index + 1) * window_seconds)
+
+
+def window_grace(window_seconds: int) -> int:
+    """Clock-skew allowance at window close, in whole seconds (floored, so
+    the allowance never exceeds the published fraction)."""
+    return int(window_seconds * CONSTANTS['grant']['window_grace_fraction'])
+

fleetmesh_core-0.2.0/fleetmesh_core/accounting/capacity.py

@@ -0,0 +1,142 @@
+#!/usr/bin/env python3
+"""Reference implementation of the node's own ceiling and the shed ladder.
+
+Standard library only. Every constant is read from schema/constants.json rather
+than hardcoded, so this file and the protocol version digest cannot disagree.
+
+A grant bounds one peer. Nothing bounded the node. `Meter` is per peer and the
+tick loops them, so twenty anchor peerings each perfectly inside its grant is
+960,000 events an hour with nobody at fault anywhere: every branch within its
+limit, and the trunk with none. That is the fragility this file answers.
+
+Two decisions worth stating here rather than leaving to a reader.
+
+**The total is the operator's number and this file states no default.** The
+specification says connectivity and not capability is what separates one
+deployment from another, so a Raspberry Pi and a forty-core gateway both declare
+anchor and no per-class table could be honest about either. What is normative is
+the ladder. A node with no declared total measures its pressure and reports it
+and sheds nothing, because refusing an honest peer against a limit nobody chose
+is worse than the overload it would be avoiding. `suggest` exists so an operator
+has a number to start from rather than a blank.
+
+**Shedding is announced, and it is not adverse.** Every rung says what it is
+doing - a decline code, a republished coverage claim, an amend carrying
+`cause: capacity`. A node that shed quietly would be read as partitioned, which
+is the one conclusion this protocol keeps having to unlearn, and a subject that
+read a capacity shed as a remedy would price its issuer for owning a small
+machine.
+"""
+from __future__ import annotations
+
+from typing import Iterable, Mapping, Optional, Sequence
+
+from . import window
+
+from ..wire import schema_files# window.as_limits: a grant carries integers
+from ..wire.interfaces import CapacitySummary
+
+C = schema_files.load_constants()['capacity']
+
+COUNTERS: tuple[str, ...] = tuple(C['counters'])
+LADDER: tuple[tuple[float, str], ...] = tuple((r['at'], r['action']) for r in C['shed'])
+ACTIONS: tuple[str, ...] = tuple(a for _, a in LADDER)
+
+
+def pressure(measured: Mapping[str, int | float], total: Mapping[str, int | float]) -> tuple[float, Optional[str]]:
+    """(fraction, binding counter) for one window's aggregate against a total.
+
+    The fraction is the max over counters, not a mean: a node that has run out
+    of one thing has run out. `total` is a dict of the same counter names; a
+    counter the operator did not declare is not measured, and a total of zero or
+    less is not a declaration.
+    """
+    worst: float = 0.0
+    binding: Optional[str] = None
+    for name in COUNTERS:
+        cap = total.get(name)
+        if not cap or cap <= 0:
+            continue
+        share = measured.get(name, 0) / float(cap)
+        if share > worst:
+            worst, binding = share, name
+    return worst, binding
+
+
+def rungs(p: float) -> list[str]:
+    """Every shed action engaged at pressure p, in ladder order."""
+    return [a for at, a in LADDER if p >= at]
+
+
+def engaged(p: float, held: Sequence[str] = ()) -> list[str]:
+    """The rungs a node should be holding now, given what it holds already.
+
+    Rungs engage each at its own threshold and release together below
+    `restore_below`. Releasing each at the threshold that engaged it would flap
+    a node sitting on a boundary, and each flap costs its peers an amend.
+    """
+    if p < C['restore_below']:
+        return []
+    now = set(rungs(p)) | set(held)
+    return [a for a in ACTIONS if a in now]
+
+
+def shed_floor(probation: Mapping[str, int | float]) -> dict[str, int]:
+    """The lowest a capacity shed may take a limit, from the probation ceilings.
+
+    Deliberately not the probation ceiling itself. A peering opens at that
+    ceiling, so a floor there would make the amend_down rung do nothing at all
+    for exactly the peers a busy node has most of - declared and never read,
+    which is a shape this specification keeps finding in itself. Deliberately
+    not zero either: zero for 24 hours is what S3 does to an offender, and a
+    shed is not a remedy. What is left is enough for a receipt and a trickle,
+    which is what keeps a small peering accountable rather than silent.
+    """
+    f: float = C['shed_floor_fraction']
+    # Floored, like every other limit. A fractional floor and an integer result
+    # do not compare the way anyone expects: max(335544.3, x) written into a
+    # grant becomes 335544, which is below the floor it was just held to.
+    return window.as_limits({k: v * f for k, v in probation.items()})
+
+
+def reduce(limits: Mapping[str, int | float], floor: Mapping[str, int | float], fraction: Optional[float] = None) -> dict[str, int]:
+    """Scale a grant's limits for a capacity shed, never below the floor.
+
+    A capacity shed makes a peer smaller and never makes it a stranger: the tier
+    does not move and the peering is not ended. That is what separates it from
+    an S2, which is the ladder's business and not this file's. Pass the floor
+    from `shed_floor`.
+    """
+    f = C['amend_down_fraction'] if fraction is None else fraction
+    return window.as_limits({k: max(floor.get(k, 0), v * f) if k in floor else v * f
+                             for k, v in limits.items()})
+
+
+def suggest(windows: Iterable[Mapping[str, int | float]]) -> dict[str, int | float]:
+    """A total to start from, per counter: the largest window observed.
+
+    `windows` is an iterable of aggregate measurements, one per closed window.
+    This is a report of what the machine has already carried and not a claim
+    about what it can. An operator raises it deliberately or lowers it after
+    watching the box, and either way the number is theirs.
+    """
+    out: dict[str, int | float] = {}
+    for w in windows:
+        for name in COUNTERS:
+            v = w.get(name, 0)
+            if v > out.get(name, 0):
+                out[name] = v
+    return out
+
+
+def summary(measured: Mapping[str, int | float], total: Mapping[str, int | float]) -> CapacitySummary:
+    """What the health block prints. Undeclared is a state, not a zero."""
+    if not any(total.get(n) for n in COUNTERS):
+        return {'declared': False, 'pressure': None, 'binding': None,
+                'rungs': [], 'measured': {k: measured.get(k, 0) for k in COUNTERS
+                                          if measured.get(k)}}
+    p, binding = pressure(measured, total)
+    return {'declared': True, 'pressure': round(p, 4), 'binding': binding,
+            'rungs': rungs(p),
+            'measured': {k: measured.get(k, 0) for k in COUNTERS if measured.get(k)}}
+