zeropx-layercomp 0.1.0__tar.gz

zeropx_layercomp-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.venv/
+build/
+dist/
+*.egg-info/
+dist_bin/
+build_pyi/
+landing/
+uv.lock

zeropx_layercomp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dr. Vander Geraldo Rodrigues da Cunha Júnior
+
+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.

zeropx_layercomp-0.1.0/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.5
+Name: zeropx-layercomp
+Version: 0.1.0
+Summary: Algebraic composition of defense-in-depth layers — pick min, sum-dB, or max correctly
+Project-URL: Homepage, https://github.com/NixEngine/zeropx-layercomp
+Project-URL: Repository, https://github.com/NixEngine/zeropx-layercomp
+Project-URL: Issues, https://github.com/NixEngine/zeropx-layercomp/issues
+Author-email: "Dr. Vander Geraldo Rodrigues da Cunha Júnior" <vgrcjr@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: audit,composition,container,cryptography,defense-in-depth,security,zk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Security
+Classifier: Topic :: Security :: Cryptography
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# zeropx-layercomp
+
+**Algebraic composition of defense-in-depth layers.** Pick the right operator (min, sum-dB, or max) based on the threat model — not by habit.
+
+## Why
+
+There is a subtle but consequential inconsistency in how the literature composes layered defenses:
+
+- **ZK / cryptographic security** uses `λ_efetiva = min{λ_alg, λ_FRI, λ_hash, ...}` — the weakest link.
+- **EM shielding / passive attenuation** uses `SE_total_dB = SE_1 + SE_2 + ...` — additive in decibels (product in linear).
+- **Consensus systems** use `max` — you fail only if the majority does.
+
+The same word "defense-in-depth" describes all three, but the arithmetic is different, and the wrong choice can inflate a bound by orders of magnitude.
+
+`layercomp` implements the decision tree and lets you feed a stack description and get the correctly composed score, with an explanation of which operator was used and why.
+
+## Install
+
+```bash
+pip install zeropx-layercomp
+```
+*(Python import module: `layercomp` | CLI command: `layercomp`)*
+
+Zero runtime dependencies. Python 3.10+.
+
+## Quick start
+
+Describe your stack in a JSON file:
+
+```json
+{
+  "layers": [
+    { "name": "arithmetization", "score": 128, "unit": "bits", "threat_model": "adversarial" },
+    { "name": "FRI",              "score": 100, "unit": "bits", "threat_model": "adversarial" },
+    { "name": "Poseidon2",        "score":  95, "unit": "bits", "threat_model": "adversarial",
+      "notes": "BBLP22 instance ~2^95, marked Unresolved by Least Authority" }
+  ]
+}
+```
+
+Then:
+
+```bash
+layercomp score my-zk-stack.json
+```
+
+Output:
+
+```
+layercomp v0.1.0
+
+Composition result
+  operator:   min
+  total:      95 bits
+  determined: Poseidon2
+
+Rationale: adversarial threat model — attacker selects weakest layer.
+Composition is the minimum score across layers.
+
+Per-layer:
+   arithmetization: 128 bits [adversarial, indep=True]
+   FRI: 100 bits [adversarial, indep=True]
+ * Poseidon2: 95 bits [adversarial, indep=True] — BBLP22 instance ~2^95, marked Unresolved by Least Authority
+```
+
+## Decision tree
+
+```
+layercomp explain
+```
+
+Prints:
+
+```
+1. Any layer ADVERSARIAL or mixed → min (most conservative)
+2. All CONSENSUS → max (honest-majority)
+3. All PASSIVE and all independent → sum-in-dB
+4. PASSIVE but dependent → downgrade to min with warning
+```
+
+## The common mistake this fixes
+
+Two frameworks routinely conflate these operators:
+
+- Container hardening scored with `SE_container = SE_ns + SE_cgroup + SE_seccomp + SE_net` is wrong under the adversarial model (attacker needs to escape *one* namespace, not all). It should be `min(...)`.
+- Meanwhile, `sum-in-dB` is the right composition for a Faraday cage against a passive EM leakage — the field really is attenuated through every layer in series.
+
+The distinction is `who is choosing the attack path`: an adversary chooses the weakest link; nature/noise flows through everything.
+
+## As a library
+
+```python
+from layercomp import Layer, ThreatModel, ScoreUnit, compose
+
+result = compose([
+    Layer("arithmetization", 128, ScoreUnit.BITS, ThreatModel.ADVERSARIAL),
+    Layer("FRI",              100, ScoreUnit.BITS, ThreatModel.ADVERSARIAL),
+    Layer("Poseidon2",         95, ScoreUnit.BITS, ThreatModel.ADVERSARIAL),
+])
+
+print(result.total)              # 95
+print(result.operator_used)      # 'min'
+print(result.layer_that_determined)  # 'Poseidon2'
+print(result.rationale)          # human-readable explanation
+```
+
+## Testing
+
+```bash
+pip install -e ".[test]"
+python -m pytest tests/ -v
+```
+
+## Companion tools
+
+`zeropx-layercomp` is part of the ZeroPx Auditor's Toolkit of zero-dependency Python packages:
+
+- **zeropx-gguf-inspect** — static read-only inspection of GGUF model files without loading them
+- **zeropx-corpus-scan** — byte-honest SHA-256 inventory of a document corpus
+- **zeropx-receipt-chain** — append-only tamper-evident event ledger
+- **zeropx-poseidon2-goldilocks** — pure-Python Poseidon2 reference implementation over Goldilocks
+
+## Author & Provenance
+
+**Sole Author:** Dr. Vander Geraldo Rodrigues da Cunha Júnior (`vgrcjr@gmail.com`).
+
+*Technical & AI-Assisted Provenance Disclosure:* Auxiliary computational/LLM tooling was used strictly for boilerplate and test-harness scaffolding under 1:1 human architectural design, algebraic verification, code review, and sole human authorship. Zero runtime third-party or AI dependencies.
+
+## License
+
+MIT.

zeropx_layercomp-0.1.0/README.md

@@ -0,0 +1,131 @@
+# zeropx-layercomp
+
+**Algebraic composition of defense-in-depth layers.** Pick the right operator (min, sum-dB, or max) based on the threat model — not by habit.
+
+## Why
+
+There is a subtle but consequential inconsistency in how the literature composes layered defenses:
+
+- **ZK / cryptographic security** uses `λ_efetiva = min{λ_alg, λ_FRI, λ_hash, ...}` — the weakest link.
+- **EM shielding / passive attenuation** uses `SE_total_dB = SE_1 + SE_2 + ...` — additive in decibels (product in linear).
+- **Consensus systems** use `max` — you fail only if the majority does.
+
+The same word "defense-in-depth" describes all three, but the arithmetic is different, and the wrong choice can inflate a bound by orders of magnitude.
+
+`layercomp` implements the decision tree and lets you feed a stack description and get the correctly composed score, with an explanation of which operator was used and why.
+
+## Install
+
+```bash
+pip install zeropx-layercomp
+```
+*(Python import module: `layercomp` | CLI command: `layercomp`)*
+
+Zero runtime dependencies. Python 3.10+.
+
+## Quick start
+
+Describe your stack in a JSON file:
+
+```json
+{
+  "layers": [
+    { "name": "arithmetization", "score": 128, "unit": "bits", "threat_model": "adversarial" },
+    { "name": "FRI",              "score": 100, "unit": "bits", "threat_model": "adversarial" },
+    { "name": "Poseidon2",        "score":  95, "unit": "bits", "threat_model": "adversarial",
+      "notes": "BBLP22 instance ~2^95, marked Unresolved by Least Authority" }
+  ]
+}
+```
+
+Then:
+
+```bash
+layercomp score my-zk-stack.json
+```
+
+Output:
+
+```
+layercomp v0.1.0
+
+Composition result
+  operator:   min
+  total:      95 bits
+  determined: Poseidon2
+
+Rationale: adversarial threat model — attacker selects weakest layer.
+Composition is the minimum score across layers.
+
+Per-layer:
+   arithmetization: 128 bits [adversarial, indep=True]
+   FRI: 100 bits [adversarial, indep=True]
+ * Poseidon2: 95 bits [adversarial, indep=True] — BBLP22 instance ~2^95, marked Unresolved by Least Authority
+```
+
+## Decision tree
+
+```
+layercomp explain
+```
+
+Prints:
+
+```
+1. Any layer ADVERSARIAL or mixed → min (most conservative)
+2. All CONSENSUS → max (honest-majority)
+3. All PASSIVE and all independent → sum-in-dB
+4. PASSIVE but dependent → downgrade to min with warning
+```
+
+## The common mistake this fixes
+
+Two frameworks routinely conflate these operators:
+
+- Container hardening scored with `SE_container = SE_ns + SE_cgroup + SE_seccomp + SE_net` is wrong under the adversarial model (attacker needs to escape *one* namespace, not all). It should be `min(...)`.
+- Meanwhile, `sum-in-dB` is the right composition for a Faraday cage against a passive EM leakage — the field really is attenuated through every layer in series.
+
+The distinction is `who is choosing the attack path`: an adversary chooses the weakest link; nature/noise flows through everything.
+
+## As a library
+
+```python
+from layercomp import Layer, ThreatModel, ScoreUnit, compose
+
+result = compose([
+    Layer("arithmetization", 128, ScoreUnit.BITS, ThreatModel.ADVERSARIAL),
+    Layer("FRI",              100, ScoreUnit.BITS, ThreatModel.ADVERSARIAL),
+    Layer("Poseidon2",         95, ScoreUnit.BITS, ThreatModel.ADVERSARIAL),
+])
+
+print(result.total)              # 95
+print(result.operator_used)      # 'min'
+print(result.layer_that_determined)  # 'Poseidon2'
+print(result.rationale)          # human-readable explanation
+```
+
+## Testing
+
+```bash
+pip install -e ".[test]"
+python -m pytest tests/ -v
+```
+
+## Companion tools
+
+`zeropx-layercomp` is part of the ZeroPx Auditor's Toolkit of zero-dependency Python packages:
+
+- **zeropx-gguf-inspect** — static read-only inspection of GGUF model files without loading them
+- **zeropx-corpus-scan** — byte-honest SHA-256 inventory of a document corpus
+- **zeropx-receipt-chain** — append-only tamper-evident event ledger
+- **zeropx-poseidon2-goldilocks** — pure-Python Poseidon2 reference implementation over Goldilocks
+
+## Author & Provenance
+
+**Sole Author:** Dr. Vander Geraldo Rodrigues da Cunha Júnior (`vgrcjr@gmail.com`).
+
+*Technical & AI-Assisted Provenance Disclosure:* Auxiliary computational/LLM tooling was used strictly for boilerplate and test-harness scaffolding under 1:1 human architectural design, algebraic verification, code review, and sole human authorship. Zero runtime third-party or AI dependencies.
+
+## License
+
+MIT.

zeropx_layercomp-0.1.0/examples/container-stack.json

@@ -0,0 +1,15 @@
+{
+  "description": "Container hardening under the adversarial model — corrects the sum-in-dB approach from EM analogy",
+  "layers": [
+    { "name": "namespaces",  "score": 40, "unit": "bits", "threat_model": "adversarial",
+      "notes": "PID/NET/MNT/UTS/IPC/USER/CGROUP — one escape suffices" },
+    { "name": "cgroups",     "score": 45, "unit": "bits", "threat_model": "adversarial",
+      "notes": "CVE-2022-0492 class demonstrated cgroup release_agent escape" },
+    { "name": "seccomp",     "score": 35, "unit": "bits", "threat_model": "adversarial",
+      "notes": "Docker default blocks ~44 syscalls; wide surface if unconfined" },
+    { "name": "capabilities","score": 50, "unit": "bits", "threat_model": "adversarial",
+      "notes": "cap-add=ALL nullifies this" },
+    { "name": "runc",        "score": 30, "unit": "bits", "threat_model": "adversarial",
+      "notes": "CVE-2019-5736 / CVE-2024-21626 / CVE-2025-31133 series" }
+  ]
+}

zeropx_layercomp-0.1.0/examples/faraday-passive.json

@@ -0,0 +1,10 @@
+{
+  "description": "Physical Faraday cage against passive EM leakage — sum-in-dB is correct here",
+  "layers": [
+    { "name": "outer mesh",       "score": 40, "unit": "dB", "threat_model": "passive", "independent": true,
+      "notes": "conductive mesh, skin depth argument" },
+    { "name": "inner foil layer", "score": 30, "unit": "dB", "threat_model": "passive", "independent": true },
+    { "name": "gasket seal",      "score": 15, "unit": "dB", "threat_model": "passive", "independent": true,
+      "notes": "seam attenuation" }
+  ]
+}

zeropx_layercomp-0.1.0/examples/zk-stack.json

@@ -0,0 +1,15 @@
+{
+  "description": "PLONK/Plonky2 stack in the adversarial model — Poseidon2 pins the bound at ~95 bits",
+  "layers": [
+    { "name": "arithmetization", "score": 128, "unit": "bits", "threat_model": "adversarial",
+      "notes": "PLONK gate/permutation constraints; bound from field size" },
+    { "name": "FRI",              "score": 100, "unit": "bits", "threat_model": "adversarial",
+      "notes": "FRI proximity gap with typical FriConfig" },
+    { "name": "Poseidon2",        "score":  95, "unit": "bits", "threat_model": "adversarial",
+      "notes": "BBLP22 instance ~2^95, Least Authority marked Unresolved" },
+    { "name": "Fiat-Shamir",      "score": 128, "unit": "bits", "threat_model": "adversarial",
+      "notes": "assuming complete transcript per Frozen Heart checklist" },
+    { "name": "impl",             "score": 120, "unit": "bits", "threat_model": "adversarial",
+      "notes": "informal upper bound; excludes CVE-2025-24802-class regressions" }
+  ]
+}

zeropx_layercomp-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "zeropx-layercomp"
+version = "0.1.0"
+description = "Algebraic composition of defense-in-depth layers — pick min, sum-dB, or max correctly"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Dr. Vander Geraldo Rodrigues da Cunha Júnior", email = "vgrcjr@gmail.com" }]
+keywords = ["security", "cryptography", "defense-in-depth", "composition", "audit", "zk", "container"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Information Technology",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Security",
+    "Topic :: Security :: Cryptography",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=7"]
+
+[project.scripts]
+layercomp = "layercomp.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/NixEngine/zeropx-layercomp"
+Repository = "https://github.com/NixEngine/zeropx-layercomp"
+Issues = "https://github.com/NixEngine/zeropx-layercomp/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/layercomp"]
+
+[tool.hatch.build.targets.sdist]
+include = ["/src", "/tests", "/examples", "/README.md", "/LICENSE"]

zeropx_layercomp-0.1.0/src/layercomp/__init__.py

@@ -0,0 +1,28 @@
+"""layercomp — algebraic composition of defense-in-depth layers.
+
+Resolves the min-vs-sum-dB tension observed across security frameworks:
+- ZK/cryptography → min (weakest-link adversarial model)
+- EM shielding → sum-in-dB (passive independent attenuation)
+- Consensus systems → max (honest-majority)
+
+The correct operator depends on (threat_model, independence, correlation)
+of each layer stack. Default is min (most conservative).
+"""
+
+from .composition import (
+    Layer,
+    ThreatModel,
+    ScoreUnit,
+    CompositionResult,
+    compose,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "Layer",
+    "ThreatModel",
+    "ScoreUnit",
+    "CompositionResult",
+    "compose",
+    "__version__",
+]

zeropx_layercomp-0.1.0/src/layercomp/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    main()

zeropx_layercomp-0.1.0/src/layercomp/cli.py

@@ -0,0 +1,131 @@
+"""layercomp CLI."""
+import argparse
+import json
+import sys
+from typing import List
+
+from .composition import Layer, ThreatModel, ScoreUnit, compose
+from . import __version__
+
+
+def _load_stack(path: str) -> List[Layer]:
+    with open(path, encoding="utf-8") as f:
+        data = json.load(f)
+    layers = []
+    for l in data["layers"]:
+        layers.append(
+            Layer(
+                name=l["name"],
+                score=float(l["score"]),
+                unit=ScoreUnit(l.get("unit", "bits")),
+                threat_model=ThreatModel(l.get("threat_model", "adversarial")),
+                independent=bool(l.get("independent", True)),
+                notes=l.get("notes"),
+            )
+        )
+    return layers
+
+
+def cmd_score(args) -> int:
+    layers = _load_stack(args.file)
+    result = compose(layers)
+
+    if args.format == "json":
+        out = {
+            "total": result.total,
+            "unit": result.unit.value,
+            "operator_used": result.operator_used,
+            "layer_that_determined": result.layer_that_determined,
+            "rationale": result.rationale,
+            "per_layer": result.per_layer,
+            "warnings": result.warnings,
+        }
+        print(json.dumps(out, indent=2, ensure_ascii=False))
+    else:
+        print(f"layercomp v{__version__}")
+        print()
+        print(f"Composition result")
+        print(f"  operator:   {result.operator_used}")
+        print(f"  total:      {result.total} {result.unit.value}")
+        if result.layer_that_determined:
+            print(f"  determined: {result.layer_that_determined}")
+        print()
+        print(f"Rationale: {result.rationale}")
+        print()
+        print("Per-layer:")
+        for name, meta in result.per_layer.items():
+            marker = " * " if name == result.layer_that_determined else "   "
+            note = f" — {meta['notes']}" if meta.get("notes") else ""
+            print(
+                f"{marker}{name}: {meta['score']} {meta['unit']} "
+                f"[{meta['threat_model']}, indep={meta['independent']}]{note}"
+            )
+        if result.warnings:
+            print()
+            print("Warnings:")
+            for w in result.warnings:
+                print(f"  ! {w}")
+
+    return 0
+
+
+def cmd_explain(args) -> int:
+    """Show the decision tree used by compose()."""
+    print(
+        """layercomp decision tree
+=======================
+
+Given a stack of defense layers, the operator is chosen as follows:
+
+  1. If ANY layer has threat_model = ADVERSARIAL, or if threat models are mixed
+     → use min (weakest-link, most conservative). This matches:
+        - ZK security: lambda_efetiva = min{lambda_alg, lambda_FRI, ...}
+        - Container escape: attacker needs to break just one namespace/cap
+        - Jurisdictional gates: one regulator denying is enough
+
+  2. If ALL layers are CONSENSUS
+     → use max (honest-majority; system fails only if majority fails). Matches:
+        - BFT protocols
+        - Multi-sig (m-of-n where n-m+1 must fail)
+
+  3. If ALL layers are PASSIVE and all independent
+     → use sum-in-dB (equivalent to product in linear). Matches:
+        - EM shielding: SE_total_dB = SE_ns + SE_cgroup + ...
+        - Statistical decorrelation of independent side channels
+        - Noise attenuation stages
+
+  4. If PASSIVE but layers are dependent
+     → downgrade to min (with warning). Correlation invalidates additivity.
+
+Notes
+-----
+- Mixed units emit a warning; composition assumes homogeneous units.
+- "Independent" means: attacker cannot use one layer's weakness to bypass another.
+- "Adversarial" is the default and safest assumption when in doubt.
+"""
+    )
+    return 0
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="layercomp",
+        description="Compose defense layers with the correct algebraic operator (min/sum-dB/max)",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    subs = parser.add_subparsers(dest="command", required=True)
+
+    p_score = subs.add_parser("score", help="Compute composed score for a defense stack")
+    p_score.add_argument("file", help="Path to JSON file describing the layer stack")
+    p_score.add_argument("--format", choices=["text", "json"], default="text")
+    p_score.set_defaults(func=cmd_score)
+
+    p_explain = subs.add_parser("explain", help="Show the decision tree used by compose()")
+    p_explain.set_defaults(func=cmd_explain)
+
+    args = parser.parse_args()
+    sys.exit(args.func(args))
+
+
+if __name__ == "__main__":
+    main()

zeropx_layercomp-0.1.0/src/layercomp/composition.py

@@ -0,0 +1,149 @@
+"""Core composition algebra."""
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import List, Optional, Dict, Any
+
+
+class ThreatModel(Enum):
+    ADVERSARIAL = "adversarial"  # attacker chooses weakest link (crypto, security bounds)
+    PASSIVE = "passive"          # random noise/leakage, all layers filter (EM shielding, statistical isolation)
+    CONSENSUS = "consensus"      # need majority to fail (BFT, multi-sig, honest-majority)
+
+
+class ScoreUnit(Enum):
+    BITS = "bits"        # cryptographic bit-security
+    DB = "dB"            # decibels (10*log10 or 20*log10 of ratio)
+    LINEAR = "linear"    # linear probability, factor, or dimensionless ratio
+    ORDINAL = "ordinal"  # relative rank only, no arithmetic guaranteed
+
+
+@dataclass
+class Layer:
+    name: str
+    score: float
+    unit: ScoreUnit = ScoreUnit.BITS
+    threat_model: ThreatModel = ThreatModel.ADVERSARIAL
+    independent: bool = True
+    notes: Optional[str] = None
+
+    def __post_init__(self):
+        if not isinstance(self.unit, ScoreUnit):
+            self.unit = ScoreUnit(self.unit)
+        if not isinstance(self.threat_model, ThreatModel):
+            self.threat_model = ThreatModel(self.threat_model)
+
+
+@dataclass
+class CompositionResult:
+    total: float
+    unit: ScoreUnit
+    operator_used: str
+    layer_that_determined: Optional[str]
+    per_layer: Dict[str, Dict[str, Any]]
+    warnings: List[str] = field(default_factory=list)
+    rationale: str = ""
+
+
+def compose(layers: List[Layer], target_unit: Optional[ScoreUnit] = None) -> CompositionResult:
+    """Compose defense layers into a single bound using the correct operator.
+
+    Decision tree:
+    - If any threat model is ADVERSARIAL, or mixed models → use min (most conservative)
+    - If all layers PASSIVE and all independent → use sum-in-dB (equivalent to product in linear)
+    - If all layers CONSENSUS → use max
+    - If dependent layers with passive/consensus model → downgrade to min with warning
+    """
+    if not layers:
+        raise ValueError("no layers provided")
+
+    warnings: List[str] = []
+    threat_models = set(l.threat_model for l in layers)
+    units = set(l.unit for l in layers)
+
+    if len(units) > 1:
+        warnings.append(
+            f"mixed units {[u.value for u in units]} — composition assumes homogeneous units; "
+            "convert layers to a single unit before composition or interpret result cautiously"
+        )
+
+    if target_unit is None:
+        target_unit = layers[0].unit
+
+    # Determine operator
+    if ThreatModel.ADVERSARIAL in threat_models:
+        primary = ThreatModel.ADVERSARIAL
+        if len(threat_models) > 1:
+            warnings.append(
+                f"mixed threat models {[t.value for t in threat_models]} — falling back to adversarial (min)"
+            )
+    elif threat_models == {ThreatModel.CONSENSUS}:
+        primary = ThreatModel.CONSENSUS
+    elif threat_models == {ThreatModel.PASSIVE}:
+        all_indep = all(l.independent for l in layers)
+        if not all_indep:
+            warnings.append(
+                "passive threat model with dependent layers — additive composition unsafe; "
+                "falling back to min"
+            )
+            primary = ThreatModel.ADVERSARIAL
+        else:
+            primary = ThreatModel.PASSIVE
+    else:
+        primary = ThreatModel.ADVERSARIAL
+
+    # Apply operator
+    if primary == ThreatModel.ADVERSARIAL:
+        operator = "min"
+        determining = min(layers, key=lambda l: l.score)
+        total = determining.score
+        det_name = determining.name
+        rationale = (
+            "adversarial threat model — attacker selects weakest layer. "
+            "Composition is the minimum score across layers."
+        )
+    elif primary == ThreatModel.PASSIVE:
+        if target_unit == ScoreUnit.DB:
+            operator = "sum-in-dB"
+            total = sum(l.score for l in layers)
+        else:
+            operator = "sum-in-dB (raw)"
+            total = sum(l.score for l in layers)
+            warnings.append(
+                f"passive composition on non-dB unit ({target_unit.value}) is unusual; "
+                "consider recasting layers in dB — result reported as raw sum"
+            )
+        det_name = None
+        rationale = (
+            "passive threat model with independent layers — attenuations add. "
+            "In dB this is sum; in linear it would be product of factors."
+        )
+    else:  # CONSENSUS
+        operator = "max"
+        determining = max(layers, key=lambda l: l.score)
+        total = determining.score
+        det_name = determining.name
+        rationale = (
+            "consensus / honest-majority model — system fails only when majority fails. "
+            "Composition is the maximum score across layers (strongest quorum member)."
+        )
+
+    per_layer = {
+        l.name: {
+            "score": l.score,
+            "unit": l.unit.value,
+            "threat_model": l.threat_model.value,
+            "independent": l.independent,
+            "notes": l.notes,
+        }
+        for l in layers
+    }
+
+    return CompositionResult(
+        total=total,
+        unit=target_unit,
+        operator_used=operator,
+        layer_that_determined=det_name,
+        per_layer=per_layer,
+        warnings=warnings,
+        rationale=rationale,
+    )

zeropx_layercomp-0.1.0/tests/test_composition.py

@@ -0,0 +1,116 @@
+"""Tests for layercomp composition algebra."""
+import pytest
+
+from layercomp import Layer, ThreatModel, ScoreUnit, compose
+
+
+class TestAdversarialMin:
+    def test_zk_stack_returns_min(self):
+        layers = [
+            Layer("alg", 128, ScoreUnit.BITS, ThreatModel.ADVERSARIAL),
+            Layer("FRI", 100, ScoreUnit.BITS, ThreatModel.ADVERSARIAL),
+            Layer("hash", 95, ScoreUnit.BITS, ThreatModel.ADVERSARIAL),
+            Layer("FS", 128, ScoreUnit.BITS, ThreatModel.ADVERSARIAL),
+            Layer("impl", 120, ScoreUnit.BITS, ThreatModel.ADVERSARIAL),
+        ]
+        r = compose(layers)
+        assert r.operator_used == "min"
+        assert r.total == 95
+        assert r.layer_that_determined == "hash"
+
+    def test_single_layer(self):
+        r = compose([Layer("only", 128)])
+        assert r.total == 128
+        assert r.operator_used == "min"
+
+    def test_mixed_threat_falls_back_to_min(self):
+        layers = [
+            Layer("crypto", 128, threat_model=ThreatModel.ADVERSARIAL),
+            Layer("shield", 40, unit=ScoreUnit.DB, threat_model=ThreatModel.PASSIVE),
+        ]
+        r = compose(layers)
+        assert r.operator_used == "min"
+        assert r.total == 40
+        assert any("mixed threat models" in w for w in r.warnings)
+
+
+class TestPassiveSumInDB:
+    def test_em_shielding_stack_returns_sum(self):
+        layers = [
+            Layer("ns", 20, ScoreUnit.DB, ThreatModel.PASSIVE, independent=True),
+            Layer("cgroup", 15, ScoreUnit.DB, ThreatModel.PASSIVE, independent=True),
+            Layer("seccomp", 25, ScoreUnit.DB, ThreatModel.PASSIVE, independent=True),
+            Layer("net", 30, ScoreUnit.DB, ThreatModel.PASSIVE, independent=True),
+        ]
+        r = compose(layers)
+        assert r.operator_used == "sum-in-dB"
+        assert r.total == 90  # 20+15+25+30
+        assert r.layer_that_determined is None
+
+    def test_passive_dependent_downgrades_to_min(self):
+        layers = [
+            Layer("l1", 20, ScoreUnit.DB, ThreatModel.PASSIVE, independent=False),
+            Layer("l2", 15, ScoreUnit.DB, ThreatModel.PASSIVE, independent=True),
+        ]
+        r = compose(layers)
+        assert r.operator_used == "min"
+        assert r.total == 15
+        assert any("dependent" in w for w in r.warnings)
+
+
+class TestConsensusMax:
+    def test_bft_stack_returns_max(self):
+        layers = [
+            Layer("node1", 100, threat_model=ThreatModel.CONSENSUS),
+            Layer("node2", 90, threat_model=ThreatModel.CONSENSUS),
+            Layer("node3", 110, threat_model=ThreatModel.CONSENSUS),
+        ]
+        r = compose(layers)
+        assert r.operator_used == "max"
+        assert r.total == 110
+        assert r.layer_that_determined == "node3"
+
+
+class TestRealWorldContradiction:
+    """Test the exact contradiction that motivated layercomp:
+    - Junior's PLONK Manifest says min for defense-in-depth
+    - Junior's Faraday-Digital Report says sum-in-dB
+    Both cannot be right for the same threat model.
+    """
+
+    def test_zk_manifest_correct_min(self):
+        """PLONK/Poseidon2 λ_efetiva = min{...}"""
+        layers = [
+            Layer("lambda_alg", 128, ScoreUnit.BITS, ThreatModel.ADVERSARIAL),
+            Layer("lambda_FRI", 100, ScoreUnit.BITS, ThreatModel.ADVERSARIAL),
+            Layer("lambda_hash", 95, ScoreUnit.BITS, ThreatModel.ADVERSARIAL),
+        ]
+        r = compose(layers)
+        assert r.total == 95
+        assert r.operator_used == "min"
+
+    def test_container_adversarial_should_be_min_not_sum(self):
+        """Corrects the Faraday-Digital error: container escape is adversarial, not passive."""
+        layers = [
+            Layer("ns", 20, ScoreUnit.BITS, ThreatModel.ADVERSARIAL),
+            Layer("seccomp", 15, ScoreUnit.BITS, ThreatModel.ADVERSARIAL),
+            Layer("cap", 25, ScoreUnit.BITS, ThreatModel.ADVERSARIAL),
+        ]
+        r = compose(layers)
+        # This is 15, NOT 60 as sum-dB would suggest
+        assert r.total == 15
+        assert r.operator_used == "min"
+
+
+class TestValidation:
+    def test_empty_stack_raises(self):
+        with pytest.raises(ValueError):
+            compose([])
+
+    def test_mixed_units_warns(self):
+        layers = [
+            Layer("bits", 128, ScoreUnit.BITS),
+            Layer("dB", 40, ScoreUnit.DB),
+        ]
+        r = compose(layers)
+        assert any("mixed units" in w for w in r.warnings)